quarkusio/quarkus · error · IllegalStateException

Mongo Client '%s' is not active

Error message

Mongo Client '%s' is not active

What it means

MongoClients.unmanagedMongoClient creates a one-off MongoClient from named config in quarkus.mongodb.clients. If the named client's 'active' flag is false, the client is intentionally disabled and Quarkus throws IllegalStateException rather than creating a connection. This prevents accidentally using a deliberately deactivated client configuration.

Source

Thrown at extensions/mongodb-client/runtime/src/main/java/io/quarkus/mongodb/runtime/MongoClients.java:145

            //force class init to prevent possible deadlock when done by mongo threads
            Class.forName("sun.net.ext.ExtendedSocketOptions", true, ClassLoader.getSystemClassLoader());
        } catch (ClassNotFoundException ignored) {
        }
    }

    /**
     * Creates an unmanaged {@link MongoClient} using the configuration for a specific client name. Callers must close
     * the client manually.
     * <p>
     * Intended for use by Mongo DB schema management tools.
     *
     * @param clientName the MongoDB client name.
     * @return a {@link MongoClient}
     */
    public MongoClient unmanagedMongoClient(String clientName) throws MongoException {
        MongoClientConfig clientConfig = mongoConfig.clients().get(clientName);
        if (!clientConfig.active()) {
            throw new IllegalStateException(String.format("Mongo Client '%s' is not active", clientName));
        }
        MongoClientSettings mongoConfiguration = createMongoConfiguration(clientConfig, clientName, false);
        return com.mongodb.client.MongoClients.create(mongoConfiguration, DRIVER_INFORMATION);
    }

    MongoClient createMongoClient(String clientName) throws MongoException {
        MongoClientConfig clientConfig = mongoConfig.clients().get(clientName);
        if (!clientConfig.active()) {
            throw new IllegalStateException(String.format("Mongo Client '%s' is not active", clientName));
        }
        return mongoClients.computeIfAbsent(clientName, new Function<String, MongoClient>() {
            @Override
            public MongoClient apply(String s) {
                MongoClientSettings mongoConfiguration = createMongoConfiguration(clientConfig, clientName, false);
                return com.mongodb.client.MongoClients.create(mongoConfiguration, DRIVER_INFORMATION);
            }
        });
    }

View on GitHub (pinned to e1c734241f)

Solutions

1. Set quarkus.mongodb.clients."<name>".active=true for the client in the active config profile
2. Remove the active=false override from profile-specific config (application.yaml for dev/test)
3. Rename the lookup to a client name that is active
4. If the client is intentionally inactive, guard the code path and skip creation instead of requesting it

Example fix

// before (application.properties)
quarkus.mongodb.clients.legacy.active=false
// after
quarkus.mongodb.clients.legacy.active=true

MongoClientConfig cfg = config.clients().get(clientName);
if (cfg == null || !cfg.active()) {
    throw new IllegalArgumentException("Client '" + clientName + "' missing or inactive — set quarkus.mongodb.clients.\"" + clientName + "\".active=true");
}

null

try {
    MongoClient client = mongoClients.unmanagedMongoClient(name);
} catch (IllegalStateException e) {
    log.errorf(e, "Mongo client '%s' is inactive; check quarkus.mongodb.clients.%s.active", name, name);
}

When it happens

Trigger: Calling unmanagedMongoClient("name") where quarkus.mongodb.clients."name".active is set to false (or the config entry exists but is inactive).

Common situations: A named client was disabled in configuration (e.g. per-environment yml sets active: false) but code still requests it; profile-specific config deactivates the client in test/dev while production code expects it; copy-pasted client config with active=false left in place.

Related errors

• Config property 'quarkus.mongodb.database' must be defined w
• <errorMessage>.formatted(clientName) (required Liquibase Mon
• Mongo client named '%s' not found
• Could not configure MongoDB client with TLS registry
• mongo config is missing for creating mongo client.

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/63f7dfab538ae958. Report an issue: GitHub.