How to Fix Spring Boot Startup Error: MongoSocketOpenException (Connection Refused) Without MongoDB Configuration

1. Background & Environment Overview

To meet business requirements, a lightweight database backup component was integrated into the project. This component supports automatic backups for data sources like MySQL and MongoDB, but our project only needs to back up MySQL databases—we do not use MongoDB at all.

However, after adding this component, the Spring Boot project failed to start, and the following exception appeared in the console:

com.mongodb.MongoSocketOpenException: Exception opening socketCaused by: java.net.ConnectException: Connection refused: connect

The confusion here is that the project had no MongoDB connection settings configured, and we had no plans to use MongoDB. Yet, the startup still failed with this connection error.

2. Troubleshooting Steps

When encountering a “Connection refused” error, the first instinct is “the client failed to connect to the database”. We followed these steps to investigate:

2.1 Verify if MongoDB is Used in the Current Project

First, we suspected that other team members might have added MongoDB-related code without our knowledge. To confirm, we checked the pom.xml file for dependencies like spring-boot-starter-data-mongodb—but found no such dependencies.

2.2 Check if the MongoDB Service is Running

Since our project clearly does not require MongoDB, we skipped this step. However, if your project does use MongoDB, follow these checks:

① Ensure the MongoDB server is running and listening on the correct port:

# Check MongoDB process
ps -ef | grep mongod
# Verify if port 27017 (MongoDB's default port) is in use
netstat -ano | findstr 27017

② Validate the connection address: By default, Spring Boot uses mongodb://localhost:27017 if no MongoDB connection address is configured. If the MongoDB server is not on the local machine, the connection will be refused.

③ Check firewall settings: If MongoDB is deployed on a remote server, ensure port 27017 is open on the server. Additionally, enable external access in the mongod.conf configuration file.

2.3 Troubleshooting Results

① No MongoDB connection settings were configured in the project;

② The pom.xml file did not include the spring-boot-starter-data-mongodb dependency.

3. Solution

3.1 Identify the Root Cause

Using IDEA plugins like Maven Helper to analyze project dependencies, we discovered that the newly added tworice-backup-starter dependency included a transitive dependency: mongodb-driver-sync. This dependency is used to support backup functionality for MongoDB databases.

Spring Boot’s auto-configuration follows the principle of “classpath conditions + configuration properties”. The MongoAutoConfiguration will load if both of the following conditions are met:

① The com.mongodb.client.MongoClient class exists in the classpath (provided by the mongodb-driver-sync dependency in our project);

② The Spring Data MongoDB auto-configuration class is available (automatically scanned by spring-boot-autoconfigure’s MongoAutoConfiguration).

In other words, you don’t need to explicitly add the spring-boot-starter-data-mongodb dependency. As long as the official MongoDB driver (mongodb-driver-sync) is present in the classpath, Spring Boot will assume you intend to use MongoDB and:

• Create a MongoClient Bean;
• Attempt to connect to mongodb://localhost:27017 by default;
• Throw a MongoSocketOpenException during startup if no local MongoDB service is running.

3.2 Fix the Issue (Disable MongoDB Auto-Configuration)

In our case, we only needed to retain the MongoClient-related classes (for the backup component) but did not want Spring Boot to automatically create a MongoDB connection. To resolve this, we disabled MongoDB auto-configuration using one of the following methods:

Method 1: Add an exclusion in the application.yml configuration file

spring:
  autoconfigure:
    exclude: 
      - org.springframework.boot.autoconfigure.mongo.MongoAutoConfiguration
      - org.springframework.boot.autoconfigure.mongo.MongoDataAutoConfiguration

Method 2: Exclude configuration classes via an annotation in the main application class

@SpringBootApplication(
    exclude = {
        MongoAutoConfiguration.class,
        MongoDataAutoConfiguration.class
    }
)
public class Application {...}

4. Summary

4.1 Symptom

Even if you only add the mongodb-driver-sync dependency (without any MongoDB configuration), Spring Boot will still attempt to connect to MongoDB during startup. If no MongoDB server is running locally, a “Connection refused” error will occur.

4.2 Root Cause

Spring Boot’s auto-configuration triggers MongoAutoConfiguration as long as it detects the com.mongodb.client.MongoClient class in the classpath (provided by the mongodb-driver-sync dependency).

4.3 Key Solution

When MongoDB auto-configuration is not needed, disable it using either:

• The spring.autoconfigure.exclude property in your configuration file;
• The @SpringBootApplication(exclude = …) annotation in your main application class.