Spring Boot Auto-Configuration: Missing HikariCP, No Error

Auto-Configuration is the mechanism that allows Spring Boot to achieve its 'just run it' experience. While critics call it magic, it is a predictable sequence of conditional logic gates that evaluate your classpath, your existing beans, and your application properties at startup — in that order.

Misunderstanding auto-configuration causes real production failures. A missing classpath dependency silently skips a critical config class and you find out at 2 AM when every database call is throwing NullPointerException. A conflicting user-defined bean triggers NoUniqueBeanDefinitionException in an environment you cannot reproduce locally. A slow startup caused by evaluating hundreds of unnecessary conditions costs 30 seconds per deployment multiplied across 50 Kubernetes replicas — time nobody budgeted for.

I have debugged all three of these. What they share is that the information was available the whole time in the Conditions Evaluation Report. The engineers involved just did not know to look there.

This guide deconstructs the spring-boot-autoconfigure module to show exactly how the framework manages bean creation using the @Conditional ecosystem. By the end, you will understand how to write your own auto-configurations, read the Conditions Report without panic, and debug missing bean issues without guessing.

How Spring Boot Auto-Configuration Eliminates Boilerplate Without Magic

Spring Boot auto-configuration is a conditional bean registration engine that inspects your classpath, existing beans, and property sources to automatically configure Spring beans that would otherwise require explicit @Bean definitions. The core mechanic is the @Conditional family of annotations — @ConditionalOnClass, @ConditionalOnMissingBean, @ConditionalOnProperty — which gate each auto-configuration class. When HikariCP is on the classpath and no DataSource bean exists, Spring Boot registers one using application.properties values. If HikariCP is absent, the DataSourceAutoConfiguration simply skips registration, and no error is thrown unless your code explicitly requires a DataSource. This is why removing the HikariCP dependency from a Spring Boot app that never injects a DataSource produces no failure — the auto-configuration class evaluates to false and does nothing. In practice, auto-configuration is ordered via @AutoConfigureBefore, @AutoConfigureAfter, and @AutoConfigureOrder to resolve dependencies between configuration classes. The spring.factories file in spring-boot-autoconfigure lists all auto-configuration candidates, and Spring Boot evaluates them in order, applying conditions against the current ApplicationContext. You can exclude specific auto-configurations via @SpringBootApplication(exclude=...) or spring.autoconfigure.exclude. Use auto-configuration to reduce manual setup for standard infrastructure — data sources, JPA, security, messaging — but always verify what gets configured by enabling debug logging (debug=true) to see positive and negative condition matches. Over-reliance without understanding the conditions leads to silent misconfiguration in production.

The Mechanics of Auto-Configuration: Classpath Discovery

When you annotate your main class with @SpringBootApplication, you are implicitly enabling @EnableAutoConfiguration. This triggers a search for a file named META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports in Spring Boot 3.x, or META-INF/spring.factories in Spring Boot 2.x, across every JAR on your classpath.

Inside these files is a flat list of fully qualified configuration class names. Spring Boot attempts to load all of them. Here is where the conditional logic takes over: every class in that list is annotated with one or more @Conditional annotations that are evaluated before any @Bean method is executed. A configuration class only runs its @Bean methods if every condition on the class passes. If a single condition fails — classpath missing a class, property not set, required bean absent — the entire configuration class is skipped. Silently.

This is the mechanism that makes a single spring-boot-starter-data-jpa dependency configure DataSource, EntityManagerFactory, TransactionManager, and Hibernate dialect without you writing a line of configuration XML. It is also the mechanism that silently does nothing when HikariCP disappears from your resolved classpath due to a dependency conflict.

package io.thecodeforge.autoconfig;

import org.springframework.boot.autoconfigure.AutoConfiguration;
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;
import javax.sql.DataSource;
import com.zaxxer.hikari.HikariDataSource;
import com.zaxxer.hikari.HikariConfig;

/**
 * io.thecodeforge: Production-grade conditional configuration.
 *
 * Three conditions must ALL pass for this class to execute:
 *   1. HikariDataSource must be on the classpath
 *   2. The property forge.database.enabled must be true (or absent — matchIfMissing)
 *   3. No DataSource bean may already exist in the context
 *
 * If any condition fails, this entire class is silently skipped.
 * No error. No warning. No log line at INFO or WARN level.
 * The Conditions Evaluation Report at debug=true is the only place this skip is recorded.
 */
@AutoConfiguration  // Preferred over @Configuration for auto-config classes in Spring Boot 3.x
@ConditionalOnClass(HikariDataSource.class)
@ConditionalOnProperty(
    name = "forge.database.enabled",
    havingValue = "true",
    matchIfMissing = true  // Activates even when property is absent — opt-out model
)
public class ForgeDbAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean(DataSource.class)  // Class-level check — if ANY DataSource bean exists, skip this
    public DataSource dataSource(ForgeDataSourceProperties props) {
        HikariConfig config = new HikariConfig();
        config.setJdbcUrl(props.getUrl());
        config.setUsername(props.getUsername());
        config.setPassword(props.getPassword());
        config.setMaximumPoolSize(props.getMaxPoolSize());
        config.setConnectionTimeout(props.getConnectionTimeoutMs());
        return new HikariDataSource(config);
    }
}

Debugging the Magic: The Conditions Evaluation Report

The biggest source of frustration with auto-configuration is not that it fails — it is that it fails silently. A condition evaluates to false, the config class is skipped, and Spring Boot moves on without logging anything at INFO level. You are left with a missing bean and no obvious explanation.

The Conditions Evaluation Report fixes this. Add debug=true to application.properties and restart. Spring Boot will print every auto-configuration class it evaluated, categorized into Positive Matches (ran and created beans), Negative Matches (skipped and why), and Unconditional Classes (always run regardless of conditions). Each entry in Negative Matches shows the exact @Conditional annotation that failed and the value it tested against.

This report is also available at runtime without a restart via the Actuator /actuator/conditions endpoint. The JSON format is parseable, diffable between deployments, and can be integrated into your CI pipeline to detect configuration drift.

I treat the Conditions Report as the first tool, not the last resort. When a bean is missing, I check the report before I check the code.

package io.thecodeforge.debug;

import org.springframework.boot.ApplicationArguments;
import org.springframework.boot.ApplicationRunner;
import org.springframework.context.ApplicationContext;
import org.springframework.stereotype.Component;
import javax.sql.DataSource;

/**
 * io.thecodeforge: Startup validation that fails fast if critical beans are absent.
 *
 * This pattern catches silent auto-configuration skips at boot time
 * instead of at runtime under production traffic.
 *
 * Place in the root application package so @ComponentScan picks it up.
 * Remove from test contexts with @Profile("!test") if needed.
 */
@Component
public class ForgeStartupValidator implements ApplicationRunner {

    private final ApplicationContext context;

    public ForgeStartupValidator(ApplicationContext context) {
        this.context = context;
    }

    @Override
    public void run(ApplicationArguments args) {
        validateCriticalBean(DataSource.class,
            "DataSource bean is absent. Check the Conditions Evaluation Report: " +
            "run with debug=true or query /actuator/conditions. " +
            "Likely cause: HikariCP missing from resolved classpath due to dependency conflict.");
    }

    private void validateCriticalBean(Class<?> type, String failureMessage) {
        if (context.getBeanNamesForType(type).length == 0) {
            throw new IllegalStateException(failureMessage);
        }
    }
}

Why You Build Custom Auto-Configuration and the One File That Controls It All

You don't write auto-configuration for fun. You write it because you own a shared library—an audit logger, a rate limiter, a security filter—that every service in your org consumes. Without auto-configuration, each team copies your bean definitions, misses one, and calls you at 2 AM.

The entry point is a file nobody talks about: META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports. No XML. No magic. Just a flat list of fully qualified class names, one per line. Spring Boot iterates that file at startup and processes every class you listed.

Your class must be annotated @Configuration. But if you stop there, you've just created a regular config that always loads. That's not auto-configuration, that's a global tax. Real auto-configuration only activates when conditions are met—when a driver is on the classpath, when a property is set, when a bean is missing. That's what @Conditional family is for.

// io.thecodeforge — java tutorial

package io.thecodeforge.audit;

import org.springframework.boot.autoconfigure.AutoConfiguration;
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@AutoConfiguration
@ConditionalOnClass(name = "io.thecodeforge.audit.AuditClient")
public class AuditAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    public AuditService auditService() {
        return new AuditService();
    }
}

// AutoConfiguration.imports content:
// io.thecodeforge.audit.AuditAutoConfiguration

Conditional Guards: The Valve That Prevents Your Library from Taking Down Every App

An auto-configuration that always runs is a liability. If you register a bean that pulls in a dependency that isn't there, the app crashes at startup. That's why every auto-configuration class is wrapped in @Conditional guards.

Think of conditions as valves. @ConditionalOnClass checks if a jar is on the classpath. @ConditionalOnBean checks if some other component is already registered. @ConditionalOnProperty reads application.properties and lets the user opt out without removing the dependency. @ConditionalOnMissingBean is the most important: it says "only create this default bean if the user hasn't already defined one." That's how you give teams control—they override your default by writing their own @Bean.

You can also write your own Condition implementation. Implement org.springframework.context.annotation.Condition, override matches(), and reference it with @Conditional(MyCustomCondition.class). Use this when you need to check environment variables, cloud metadata, or runtime flags that the built-in annotations don't cover.

// io.thecodeforge — java tutorial

package io.thecodeforge.db;

import org.springframework.boot.autoconfigure.AutoConfiguration;
import org.springframework.boot.autoconfigure.condition.*;
import org.springframework.context.annotation.Bean;

import javax.sql.DataSource;

@AutoConfiguration
@ConditionalOnClass(name = "com.mysql.cj.jdbc.Driver")
@ConditionalOnProperty(name = "io.thecodeforge.db.enabled", havingValue = "true", matchIfMissing = true)
public class DatabaseAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    public DataSource dataSource() {
        // Only invoked if MySQL driver is on classpath
        // AND property is not explicitly set to false
        // AND no other DataSource bean exists
        return new com.zaxxer.hikari.HikariDataSource();
    }
}

Disabling Auto-Configuration: The Override Pattern Your Future Self Will Thank You For

Sometimes a library's auto-configuration is wrong for your app. Maybe you brought in spring-boot-starter-data-jpa but you're using a different ORM. Maybe the default DataSource doesn't match your cloud environment. You don't break the dependency—you disable the auto-configuration.

Two ways. First, in application.properties: spring.autoconfigure.exclude=org.springframework.boot.autoconfigure.orm.jpa.HibernateJpaAutoConfiguration. Add a comma-separated list if you need multiple exclusions. This is the quick fix and the one you'll use when you're debugging a startup error at 4 PM on Friday.

Second, on the main @SpringBootApplication class: @SpringBootApplication(exclude = HibernateJpaAutoConfiguration.class). This is compile-time safe and survives refactors. IDE-friendly. Use this for permanent exclusions.

If you own a library and want to let users disable your entire auto-configuration, expose a property like io.thecodeforge.autoconfigure.enabled=false and guard every @Bean with @ConditionalOnProperty. Nobody will hate you for giving them an off switch.

// io.thecodeforge — java tutorial

package io.thecodeforge;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.autoconfigure.orm.jpa.HibernateJpaAutoConfiguration;

@SpringBootApplication(exclude = {
    HibernateJpaAutoConfiguration.class,
    org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration.class
})
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

// Alternative: application.properties
// spring.autoconfigure.exclude=
//   org.springframework.boot.autoconfigure.orm.jpa.HibernateJpaAutoConfiguration,
//   org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration

The First 100 Milliseconds: What Happens When You Boot an Auto-Configured App

Before your first @Bean ever gets created, Spring Boot already decided your datasource, your JSON mapper, and your security filter chain. You never wrote those beans. They just appeared. That's the whole point of auto-configuration — but understanding when it fires saves you from blaming the framework when things break.

At startup, Spring Boot scans META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports. That file lists every auto-configuration class on the classpath. No guessing. No reflection magic. Just a flat list of candidates. Each candidate gets evaluated against the current environment — which beans already exist, which classes are on the classpath, what properties you set.

This all happens before your application context is fully wired. The framework builds a decision tree in milliseconds, then commits to a set of auto-configured beans. If a condition fails — say, DataSourceAutoConfiguration because you already defined your own — it simply skips that config. No side effects. No errors. Just silent delegation. This is why disabling auto-configuration is explicit: you are telling Spring "I already handled this, stay out."

// io.thecodeforge — java tutorial

import org.springframework.boot.autoconfigure.AutoConfigurationImportEvent;
import org.springframework.boot.autoconfigure.AutoConfigurationImportListener;

public class AutoConfigTiming implements AutoConfigurationImportListener {

    @Override
    public void onAutoConfigurationImport(AutoConfigurationImportEvent event) {
        // Fires BEFORE bean creation — just the candidate list
        System.out.println("Candidates at startup: " + event.getCandidateConfigurations());
        System.out.println("Exclusions: " + event.getExclusions());
        
        // If you see your config here, it's being evaluated — not yet instantiated
    }
}

Own the Onion: How to Build a Custom Auto-Configuration That Won't Leak

Writing custom auto-configuration is a rite of passage for library authors. Get it wrong, and your users will curse your library for stealing startup time or breaking their app silently. Get it right, and you become the dependency everyone trusts.

The single file you need: META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports. One class per line. That's your contract. But that file is the output of your design. The real work is in the @AutoConfiguration class itself.

Structure your auto-configuration like an onion: outer layer is the public API, inner layer is the conditional guard. Always put @ConditionalOnClass for your library's main dependency — if it's not on the classpath, bail immediately. Then add @ConditionalOnProperty so users can toggle your config without removing jars. Finally, expose a clean @ConfigurationProperties class so users can override defaults without touching your beans.

Never, ever create beans unconditionally. Every bean you auto-create takes time and memory. Your auto-configuration is a guest in someone else's application; be polite. Use @AutoConfigureOrder if your config must run before or after another. And for the love of production, write an autoconfigure module separate from your library code — users who hate auto-configuration can just exclude the module entirely.

// io.thecodeforge — java tutorial

package com.mylib.autoconfigure;

import com.mylib.core.FeatureEngine;
import org.springframework.boot.autoconfigure.AutoConfiguration;
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;

@AutoConfiguration
@ConditionalOnClass(FeatureEngine.class)
@ConditionalOnProperty(prefix = "mylib", name = "enabled", havingValue = "true", matchIfMissing = true)
@EnableConfigurationProperties(MyLibProperties.class)
public class MyLibraryAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    public FeatureEngine featureEngine(MyLibProperties props) {
        return new FeatureEngine(props.getApiKey(), props.getTimeout());
    }
}

Gradually Replacing Auto-configuration

Auto-configuration is a default, not a destiny. When your application outgrows Spring Boot's assumptions—perhaps you need a custom DataSource pool or a different Jackson ObjectMapper—you must replace parts without breaking everything. The principle is incremental override: start by defining a @Bean in your configuration class that matches the auto-configured bean's type and name. Spring Boot's @ConditionalOnMissingBean ensures your bean wins. For deeper control, exclude specific auto-configuration classes via spring.autoconfigure.exclude in application.properties, or use @EnableAutoConfiguration(exclude = {…}). When replacing, always test with the Conditions Evaluation Report to confirm your bean is active and the default is gone. The why is stability: replacing everything at once cascades failures. Instead, swap one bean at a time, verify each change, and only then move to the next. This gradual approach mirrors how you'd refactor legacy code—safe, traceable, and reversible.

// io.thecodeforge — java tutorial
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class CustomDataSourceConfig {

    @Bean
    @ConditionalOnMissingBean
    public javax.sql.DataSource dataSource() {
        return new com.zaxxer.hikari.HikariDataSource();
    }
}

6. Conclusion

Spring Boot Auto-Configuration is not magic—it's a disciplined system of classpath scanning, conditional annotations, and property-driven overrides. The core advantage is speed: you skip hundreds of lines of boilerplate and start with sensible defaults. Yet the real power is control. You now know how to debug auto-configuration with the Conditions Evaluation Report, disable what you don't need, build custom auto-configurations without leaking internals, and gradually replace defaults as your application evolves. Each technique serves a single purpose: keeping your codebase maintainable as constraints change. Remember, Spring Boot auto-configuration is a scaffold, not a prison. The moment a default no longer fits, you have the tools—@ConditionalOnMissingBean, exclude filters, custom starters—to reshape it. Write simple configurations, lean on the report for diagnostics, and always favor gradual replacement. Your future self will thank you when a library upgrade doesn't break your entire app.

// io.thecodeforge — java tutorial
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}