Introduction

Spring Boot will auto-configure MongoDB as soon as the right classes appear on the classpath and it believes a Mongo setup is possible. If a module includes the Mongo starter only transitively, or if certain profiles should run without a database, you need to stop that auto-configuration explicitly.

What Boot is auto-configuring

When spring-boot-starter-data-mongodb is present, Boot can create beans such as:

• 'MongoClient'
• 'MongoTemplate'
• Mongo repository infrastructure

That is convenient when the application really uses MongoDB. It becomes a problem when:

• tests should start without a database
• a shared starter brings Mongo in by accident
• one runtime profile uses Mongo and another does not

Disabling the auto-configuration prevents Boot from trying to create those beans during startup.

Excluding Mongo auto-configuration in code

The most direct fix is to exclude the relevant Boot classes on your application entry point:

1import org.springframework.boot.SpringApplication;
2import org.springframework.boot.autoconfigure.SpringBootApplication;
3import org.springframework.boot.autoconfigure.data.mongo.MongoDataAutoConfiguration;
4import org.springframework.boot.autoconfigure.mongo.MongoAutoConfiguration;
5
6@SpringBootApplication(exclude = {
7    MongoAutoConfiguration.class,
8    MongoDataAutoConfiguration.class
9})
10public class Application {
11    public static void main(String[] args) {
12        SpringApplication.run(Application.class, args);
13    }
14}

This works well when Mongo should be disabled everywhere in that application.

The two exclusions matter for different reasons. One covers client creation, and the other covers Spring Data integration. Excluding only one of them usually leads to half-configured behavior.

Disabling it from configuration

If you want the decision to be environment-specific, use configuration instead of annotations:

spring.autoconfigure.exclude=org.springframework.boot.autoconfigure.mongo.MongoAutoConfiguration,org.springframework.boot.autoconfigure.data.mongo.MongoDataAutoConfiguration

The YAML form is often easier to read:

1spring:
2  autoconfigure:
3    exclude:
4      - org.springframework.boot.autoconfigure.mongo.MongoAutoConfiguration
5      - org.springframework.boot.autoconfigure.data.mongo.MongoDataAutoConfiguration

This is useful in application-test.yml or another profile-specific file where Mongo should stay off.

Turning Mongo on only when you mean to

Some teams prefer to disable Boot’s Mongo setup and register their own configuration only behind a custom flag:

1import com.mongodb.client.MongoClient;
2import com.mongodb.client.MongoClients;
3import org.springframework.beans.factory.annotation.Value;
4import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
5import org.springframework.context.annotation.Bean;
6import org.springframework.context.annotation.Configuration;
7import org.springframework.data.mongodb.core.MongoTemplate;
8
9@Configuration
10@ConditionalOnProperty(name = "app.mongodb.enabled", havingValue = "true")
11public class MongoConfig {
12
13    @Bean
14    MongoClient mongoClient(@Value("${spring.data.mongodb.uri}") String uri) {
15        return MongoClients.create(uri);
16    }
17
18    @Bean
19    MongoTemplate mongoTemplate(MongoClient mongoClient) {
20        return new MongoTemplate(mongoClient, "sample");
21    }
22}

Then a profile can opt in:

app.mongodb.enabled=true
spring.data.mongodb.uri=mongodb://localhost:27017/sample

This pattern makes the dependency explicit instead of accidental.

Verifying that the exclusion worked

The fastest manual check is startup logging with Boot’s debug report:

./mvnw spring-boot:run -Dspring-boot.run.arguments=--debug

You can also write a small test:

1import org.junit.jupiter.api.Test;
2import org.springframework.beans.factory.annotation.Autowired;
3import org.springframework.boot.test.context.SpringBootTest;
4import org.springframework.context.ApplicationContext;
5
6import static org.assertj.core.api.Assertions.assertThat;
7
8@SpringBootTest
9class MongoDisabledTest {
10
11    @Autowired
12    ApplicationContext context;
13
14    @Test
15    void mongoTemplateIsAbsent() {
16        assertThat(context.containsBean("mongoTemplate")).isFalse();
17    }
18}

The point is not just to silence an error. The point is to prove the application context matches the intended architecture.

Common Pitfalls

One common mistake is excluding only MongoAutoConfiguration and leaving MongoDataAutoConfiguration enabled. Spring Data then still tries to wire Mongo-related infrastructure and startup can fail in confusing ways.

Another issue is forgetting about reactive Mongo support. If the reactive starter is on the classpath, it has its own auto-configuration classes and may need separate exclusion.

Teams also get caught by explicit annotations such as @EnableMongoRepositories. If you add that manually anywhere, Boot exclusions alone may not be enough because repository scanning has been reintroduced deliberately.

Finally, check the dependency tree. If Mongo came from a transitive dependency and you do not need it at all, excluding that dependency upstream may be cleaner than disabling Boot behavior downstream.

Summary

• Spring Boot enables Mongo support automatically when the starter is on the classpath.
• Exclude both MongoAutoConfiguration and MongoDataAutoConfiguration when you want it off.
• Use annotation-based exclusion for a global decision and configuration-based exclusion for profile-specific behavior.
• Prefer explicit custom configuration if Mongo should exist only behind a feature flag.
• Verify the result with startup diagnostics or a context test instead of assuming the exclusion worked.