How to Disable Spring Data Auto-Configuration in Spring Boot

Spring Boot's auto-configuration is a double-edged sword. On one hand, it saves you from writing boilerplate XML and Java config for common infrastructure like data sources, JPA repositories, and transaction managers. On the other hand, it can silently pull in dependencies you never asked for, causing classpath scanning nightmares and startup failures in production. I've seen this happen at 2 AM on a Black Friday sale when a seemingly innocent update to a shared library brought in HikariCP and MySQL driver into a service that was supposed to be a lightweight Redis cache layer. The result? Connection pool exhaustion, OOM kills, and a very angry VP of Engineering.

In this tutorial, we'll cover the exact mechanisms to disable Spring Data auto-configuration in Spring Boot 3.2. You'll learn the three main approaches: annotation-level exclusions, property-based exclusions, and conditional configuration. We'll also dive into production incidents where misconfigured auto-configuration caused data corruption and how to debug them using Spring Boot's auto-configuration report. By the end, you'll be able to confidently control which Spring Data modules (JPA, MongoDB, Redis, Cassandra, etc.) are auto-configured and which you manage manually.

Understanding Spring Boot Auto-Configuration for Data

Spring Boot's auto-configuration is driven by the @EnableAutoConfiguration annotation, which is meta-annotated on @SpringBootApplication. For Spring Data, it works by scanning the classpath for specific classes. If it finds javax.sql.DataSource, it configures a DataSource bean. If it finds org.springframework.data.jpa.repository.JpaRepository, it enables JPA repositories. This is powered by the spring.factories file in each auto-configuration JAR.

For example, spring-boot-autoconfigure-3.2.0.jar contains entries like: org.springframework.boot.autoconfigure.EnableAutoConfiguration=\ org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration,\ org.springframework.boot.autoconfigure.orm.jpa.HibernateJpaAutoConfiguration,\ org.springframework.boot.autoconfigure.data.jpa.JpaRepositoriesAutoConfiguration

When your application starts, Spring Boot evaluates these auto-configuration classes conditionally using @ConditionalOnClass, @ConditionalOnMissingBean, and @ConditionalOnProperty annotations. This is why simply having a MySQL driver on the classpath can trigger DataSourceAutoConfiguration even if you intended to use it only for a test.

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class AutoConfigDebug {
    public static void main(String[] args) {
        // Add --debug to VM arguments to see auto-configuration report
        SpringApplication.run(AutoConfigDebug.class, args);
    }
}

// Run with: java -jar myapp.jar --debug
// Output will include:
// =========================
// AUTO-CONFIGURATION REPORT
// =========================
// Positive matches:
// DataSourceAutoConfiguration matched:
//    - @ConditionalOnClass found required class 'javax.sql.DataSource' (OnClassCondition)
// Negative matches:
// JpaRepositoriesAutoConfiguration:
//    Did not match:
//       - @ConditionalOnClass did not find required class 'org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean' (OnClassCondition)

What the Official Docs Won't Tell You

The official Spring Boot documentation covers the basics of excluding auto-configuration, but it glosses over the subtle interactions between multiple auto-configuration classes. For instance, excluding DataSourceAutoConfiguration alone doesn't prevent JpaRepositoriesAutoConfiguration from trying to create a repository factory bean, which will fail because there's no DataSource. You often need to exclude multiple classes in a chain.

Another undocumented behavior: if you use @EnableJpaRepositories on a configuration class, it can still be overridden by auto-configuration if the auto-configuration class has a higher order. Spring Boot uses @AutoConfigureOrder to control precedence, and auto-configuration classes typically have order 0 (lowest precedence), but custom configurations can be overridden if they don't explicitly set @Order.

Also, the official docs don't emphasize that excluding auto-configuration via @SpringBootApplication only works for the primary application class. If you have multiple @Configuration classes, you need to use @EnableAutoConfiguration(exclude = ...) on each one, or use the global spring.autoconfigure.exclude property.

import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration;
import org.springframework.boot.autoconfigure.orm.jpa.HibernateJpaAutoConfiguration;
import org.springframework.boot.autoconfigure.data.jpa.JpaRepositoriesAutoConfiguration;

@SpringBootApplication(exclude = {
    DataSourceAutoConfiguration.class,
    HibernateJpaAutoConfiguration.class,
    JpaRepositoriesAutoConfiguration.class
})
public class ExcludeChainExample {
    public static void main(String[] args) {
        SpringApplication.run(ExcludeChainExample.class, args);
    }
}

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

Using @EnableAutoConfiguration Exclusions

The most direct way to disable Spring Data auto-configuration is by using the exclude attribute on @EnableAutoConfiguration or its composed annotation @SpringBootApplication. This approach is compile-time safe because you reference the actual class objects, so any refactoring of auto-configuration class names will cause compilation errors.

For example, to disable all JPA-related auto-configuration: @SpringBootApplication(exclude = {DataSourceAutoConfiguration.class, HibernateJpaAutoConfiguration.class, JpaRepositoriesAutoConfiguration.class})

You can also exclude by name using excludeName, which is useful when the auto-configuration class is not on the compile classpath (e.g., when using optional dependencies).

One common pitfall: if you exclude DataSourceAutoConfiguration but your code still references a DataSource bean (e.g., via @Autowired), Spring will throw a NoSuchBeanDefinitionException at startup. You must provide your own DataSource bean definition in a @Configuration class.

This approach is best for applications that need complete control over data access, such as when using a custom connection pool or a legacy ORM framework.

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import javax.sql.DataSource;
import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;

@Configuration
public class CustomDataSourceConfig {
    @Bean
    public DataSource dataSource() {
        HikariConfig config = new HikariConfig();
        config.setJdbcUrl("jdbc:postgresql://localhost:5432/mydb");
        config.setUsername("admin");
        config.setPassword("secret");
        config.setMaximumPoolSize(10);
        config.setMinimumIdle(2);
        config.setConnectionTimeout(30000);
        config.setIdleTimeout(600000);
        return new HikariDataSource(config);
    }
}

// Main application class
@SpringBootApplication(exclude = {DataSourceAutoConfiguration.class})
public class PaymentServiceApplication {
    public static void main(String[] args) {
        SpringApplication.run(PaymentServiceApplication.class, args);
    }
}

Property-Based Exclusion with spring.autoconfigure.exclude

For environment-specific exclusions, the spring.autoconfigure.exclude property is more flexible than compile-time annotations. You can set it in application.properties, application-{profile}.properties, or even as a command-line argument. This is particularly useful when you have different data access strategies for development, staging, and production.

For example, in development you might want to use an embedded H2 database with JPA auto-configuration, but in production you use a custom DataSource with manual configuration. You can exclude JPA auto-configuration only in the production profile.

The property accepts a comma-separated list of fully qualified class names. Spring Boot also supports a YAML list format: spring: autoconfigure: exclude: - org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration

One important nuance: property-based exclusions are processed after annotation-based exclusions. If both are specified, the union of all exclusions is applied. This can lead to double-exclusion warnings in the logs, but it's harmless.

However, there's a catch: if you mistype a class name in the property, Spring Boot silently ignores it. Always verify with the auto-configuration report that your exclusions are taking effect.

# Disable all JPA auto-configuration in production
spring.autoconfigure.exclude=\
  org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration,\
  org.springframework.boot.autoconfigure.orm.jpa.HibernateJpaAutoConfiguration,\
  org.springframework.boot.autoconfigure.data.jpa.JpaRepositoriesAutoConfiguration,\
  org.springframework.boot.autoconfigure.jdbc.JdbcTemplateAutoConfiguration

# Custom DataSource configuration is provided by CustomDataSourceConfig.java
# No need for JPA, we use plain JDBC for high-throughput analytics

# Verify exclusions by enabling debug logging
logging.level.org.springframework.boot.autoconfigure=DEBUG

Conditional Configuration with @ConditionalOnClass and @ConditionalOnMissingBean

For advanced scenarios, you can create your own auto-configuration that conditionally disables Spring Data modules. This is useful when building shared libraries or frameworks that need to be compatible with multiple data access strategies.

Use @ConditionalOnClass to trigger your configuration only when a specific class is present. For example, you can create a configuration that only activates when both Redis and JPA are on the classpath, and then disable JPA repositories to avoid conflicts.

Use @ConditionalOnMissingBean to prevent duplicate bean definitions. If a user has already defined a DataSource bean, your auto-configuration should skip creating one.

Spring Boot also provides @AutoConfigureBefore and @AutoConfigureAfter to control ordering. For instance, you can ensure your custom configuration runs after the default auto-configuration and overrides it.

This approach requires deep understanding of Spring Boot's auto-configuration internals and is typically used by framework developers rather than application developers.

import org.springframework.boot.autoconfigure.AutoConfigureAfter;
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration;
import org.springframework.context.annotation.Configuration;
import javax.sql.DataSource;

@Configuration
@ConditionalOnClass(DataSource.class)
@AutoConfigureAfter(DataSourceAutoConfiguration.class)
public class CustomAutoConfiguration {
    // This configuration only runs if DataSource is on classpath
    // and after DataSourceAutoConfiguration has attempted to run
    
    // We can override beans here
    @ConditionalOnMissingBean
    public DataSource customDataSource() {
        // Custom DataSource logic
        return new CustomDataSource();
    }
}

// Register in META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
// com.example.CustomAutoConfiguration

Disabling Specific Spring Data Modules (JPA, MongoDB, Redis, etc.)

Spring Boot supports multiple Spring Data modules. Each has its own auto-configuration class. Here are the key ones for Spring Boot 3.2:

• JPA: DataSourceAutoConfiguration, HibernateJpaAutoConfiguration, JpaRepositoriesAutoConfiguration
• MongoDB: MongoAutoConfiguration, MongoDataAutoConfiguration, MongoRepositoriesAutoConfiguration
• Redis: RedisAutoConfiguration, RedisRepositoriesAutoConfiguration
• Cassandra: CassandraAutoConfiguration, CassandraDataAutoConfiguration, CassandraRepositoriesAutoConfiguration
• Elasticsearch: ElasticsearchDataAutoConfiguration, ElasticsearchRepositoriesAutoConfiguration

To disable only MongoDB auto-configuration, for example: @SpringBootApplication(exclude = {MongoAutoConfiguration.class, MongoDataAutoConfiguration.class})

If you're using multiple data stores, you can selectively enable only the ones you need. For instance, a service that uses JPA for transactional data and Redis for caching should exclude MongoDB and Cassandra auto-configuration to avoid unnecessary beans.

One common mistake: excluding MongoAutoConfiguration but forgetting to exclude MongoRepositoriesAutoConfiguration. This results in repository beans being created without a MongoTemplate, causing late startup failures.

import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.autoconfigure.data.mongo.MongoDataAutoConfiguration;
import org.springframework.boot.autoconfigure.data.mongo.MongoRepositoriesAutoConfiguration;
import org.springframework.boot.autoconfigure.mongo.MongoAutoConfiguration;
import org.springframework.boot.autoconfigure.data.redis.RedisAutoConfiguration;
import org.springframework.boot.autoconfigure.data.redis.RedisRepositoriesAutoConfiguration;

@SpringBootApplication(exclude = {
    // Disable MongoDB auto-configuration
    MongoAutoConfiguration.class,
    MongoDataAutoConfiguration.class,
    MongoRepositoriesAutoConfiguration.class,
    // Disable Redis repositories (keep RedisTemplate)
    RedisRepositoriesAutoConfiguration.class
})
public class MultiDataStoreApp {
    public static void main(String[] args) {
        SpringApplication.run(MultiDataStoreApp.class, args);
    }
}

// This app uses JPA for main database and Redis for caching
// but does not need MongoDB or Redis repositories

Debugging Auto-Configuration Issues in Production

When auto-configuration goes wrong in production, you need to diagnose quickly. Spring Boot provides several tools:

1. Auto-configuration report: Enable by setting debug=true in application.properties or passing --debug as a VM argument. This prints a detailed report of all auto-configuration classes that matched, did not match, and were excluded.
2. Actuator endpoint: If you have spring-boot-starter-actuator, the /actuator/conditions endpoint exposes the same information as JSON. This is invaluable for remote debugging.
3. Beans endpoint: /actuator/beans shows all beans in the context, including their type and dependencies. Look for unexpected DataSource or EntityManagerFactory beans.
4. Logging HTTP headers: Add logging.level.org.springframework.boot.autoconfigure=TRACE to see every condition evaluation in real-time.

In production, never use debug=true permanently as it prints sensitive configuration details. Instead, enable it temporarily via a management endpoint or use the actuator conditions endpoint with proper security.

// application.properties
management.endpoints.web.exposure.include=conditions,beans
management.endpoint.conditions.enabled=true
management.endpoint.beans.enabled=true

// Secure the endpoints
management.endpoint.conditions.roles=ADMIN
spring.security.user.name=admin
spring.security.user.password=secret

// Then access:
// GET /actuator/conditions
// Response includes:
// {
//   "contexts": {
//     "application": {
//       "positiveMatches": {
//         "DataSourceAutoConfiguration": {
//           "condition": "OnClassCondition",
//           "message": "@ConditionalOnClass found required class 'javax.sql.DataSource'"
//         }
//       },
//       "negativeMatches": {
//         "JpaRepositoriesAutoConfiguration": {
//           "condition": "OnClassCondition",
//           "message": "@ConditionalOnClass did not find required class 'org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean'"
//         }
//       }
//     }
//   }
// }

Best Practices and Common Pitfalls

After years of dealing with auto-configuration issues, here are the practices that have saved my team countless hours:

1. Always run the auto-configuration report in CI/CD: Add a step that starts the application with --debug and fails the build if unexpected auto-configuration classes match. This catches dependency drift early.
2. Use a centralized exclusion list: In a microservices architecture, maintain a shared configuration library that defines common exclusions. This prevents each team from reinventing the wheel.
3. Test exclusion scenarios: Write integration tests that verify certain auto-configuration classes are NOT present in the context. Use @SpringBootTest with specific profiles.
4. Document exclusions: Add comments in application.properties or the main class explaining why each exclusion is needed. Future developers will thank you.
5. Beware of @SpringBootApplication scanning: If you have multiple @Configuration classes, auto-configuration exclusions on the main class may not apply to all of them. Use @EnableAutoConfiguration on each configuration class that needs exclusions.
6. Version compatibility: Auto-configuration class names can change between Spring Boot versions. Use your IDE's auto-complete to ensure you're referencing the correct classes for your version.

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.context.ApplicationContext;
import static org.junit.jupiter.api.Assertions.assertNotNull;
import static org.junit.jupiter.api.Assertions.assertNull;

@SpringBootTest(properties = {
    "spring.autoconfigure.exclude=org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration"
})
public class AutoConfigExclusionTest {

    @Autowired
    private ApplicationContext context;

    @Test
    void testDataSourceNotAutoConfigured() {
        // Verify that DataSourceAutoConfiguration was excluded
        boolean hasDataSource = context.containsBean("dataSource");
        // If we have a custom DataSource bean, it should exist
        // But if we don't, it should be null
        assertNull(context.getBeanNamesForType(javax.sql.DataSource.class));
    }

    @Test
    void testNoJpaRepositories() {
        // Verify no JPA repository beans are present
        String[] repoBeans = context.getBeanNamesForAnnotation(
            org.springframework.stereotype.Repository.class);
        assertNotNull(repoBeans);
        // We expect zero JPA repositories if excluded
        // But custom repositories might exist
    }
}