quarkusio/quarkus · error · IllegalArgumentException

Mongo client named '%s' not found

Error message

Mongo client named '%s' not found

What it means

The Liquibase MongoDB extension needs to obtain the MongoClient configuration for the client it should run migrations against. When quarkus.liquibase-mongodb.mongo-client-name (or the client name derived from the config group) does not match any key in quarkus.mongodb.clients.*, the lookup returns null and this IllegalArgumentException is thrown at startup before Liquibase runs.

Source

Thrown at extensions/liquibase/liquibase-mongodb/runtime/src/main/java/io/quarkus/liquibase/mongodb/runtime/LiquibaseMongodbRecorder.java:62

            @Override
            public LiquibaseMongodbFactory get() {
                LiquibaseMongodbBuildTimeClientConfig buildTimeClientConfig = getRequiredConfig(
                        buildTimeConfig.clientConfigs(),
                        "Liquibase Mongo config (changeLog) named '%s' not found");

                LiquibaseMongodbClientConfig liquibaseMongodbClientConfig = getRequiredConfig(
                        runtimeConfig.getValue().clientConfigs(),
                        "Liquibase Mongo client config named '%s' not found");

                MongoClientConfig mongoClientConfig;
                String clientNameSelected;
                if (liquibaseMongodbClientConfig.mongoClientName().isPresent()) {
                    // keep compatibility with the legacy configuration which makes possible set the mongo-client-name
                    String forceMongoClientName = liquibaseMongodbClientConfig.mongoClientName().get();
                    mongoClientConfig = mongodbRuntimeConfig.getValue().clients().get(forceMongoClientName);
                    if (mongoClientConfig == null) {
                        throw new IllegalArgumentException(
                                "Mongo client named '%s' not found".formatted(forceMongoClientName));
                    }
                    clientNameSelected = forceMongoClientName;
                } else if (MongoConfig.isDefaultClient(clientName)) {
                    mongoClientConfig = mongodbRuntimeConfig.getValue().clients().get(clientName);
                    clientNameSelected = clientName;
                } else {
                    mongoClientConfig = getRequiredConfig(mongodbRuntimeConfig.getValue().clients(),
                            "Mongo client named '%s' not found");
                    clientNameSelected = clientName;
                }
                return new LiquibaseMongodbFactory(
                        liquibaseMongodbClientConfig,
                        buildTimeClientConfig,
                        mongoClientConfig,
                        clientNameSelected);
            }
        };

View on GitHub (pinned to e1c734241f)

Solutions

1. Add a matching client config: define quarkus.mongodb.<client-name>.connection-string (etc.) for the name referenced by quarkus.liquibase-mongodb.mongo-client-name
2. Fix the typo / remove quarkus.liquibase-mongodb.mongo-client-name if the default client (quarkus.mongodb.*) is intended
3. Verify effective config per profile (mvn quarkus:dev and check config dump) since the client may only exist in one profile

Example fix

// before
quarkus.liquibase-mongodb.mongo-client-name=orders-db
# no quarkus.mongodb.orders-db.* defined
// after
quarkus.liquibase-mongodb.mongo-client-name=orders-db
quarkus.mongodb.orders-db.connection-string=mongodb://localhost:27017
quarkus.mongodb.orders-db.database=orders

String name = config.liquibaseMongoClientName();
Map<String, MongoClientConfig> clients = mongodbConfig.clients();
if (name != null && !clients.containsKey(name)) {
    throw new IllegalArgumentException(
        "quarkus.liquibase-mongodb.mongo-client-name '%s' has no matching quarkus.mongodb.%s.* config"
            .formatted(name, name));
}

try {
    liquibaseMongodbConfig.mongoClientName().ifPresent(n ->
        Objects.requireNonNull(mongoClients.get(n), "Mongo client '%s' not configured".formatted(n)));
} catch (IllegalArgumentException e) {
    log.errorf("Liquibase Mongo client misconfiguration: %s", e.getMessage());
    throw e; // fail fast at startup
}

When it happens

Trigger: quarkus.liquibase-mongodb.mongo-client-name is set to a name that has no matching entry under quarkus.mongodb.<name>.* (e.g. pointing at 'default' while only a named client exists, or a typo).

Common situations: Renaming a MongoDB client config without updating liquibase-mongodb's mongo-client-name; copy-pasting config from an app with a named client; splitting one Mongo config into named clients during a refactor; profile-specific config that only defines the client in one profile.

Related errors

• Config property 'quarkus.mongodb.database' must be defined w
• <errorMessage>.formatted(clientName) (required Liquibase Mon
• Error starting Liquibase
• mongo config is missing for creating mongo client.
• The database was not configured for the default Mongo Client

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