MongoDB active/inactive profile behavior

[zanmagerl]

Hi,
Quarkus 3.32 (#51013) introduced capability to disable default MongoDB client: https://quarkus.io/guides/mongodb#activate-or-deactivate-mongo-clients.
This allows you to disable client in case you will create it dynamically "by hand". The problem is that even if I set active: false, it still tries to encode/parse connection string and throws an error in case connection string is not valid:

Failed to start quarkus
at io.quarkus.runner.ApplicationImpl.doStart(Unknown Source)
at io.quarkus.runtime.Application.start(Application.java:112)\
at io.quarkus.runtime.ApplicationLifecycleManager.run(ApplicationLifecycleManager.java:127)
at io.quarkus.runtime.Quarkus.run(Quarkus.java:79)
at io.quarkus.runtime.Quarkus.run(Quarkus.java:50)
at io.quarkus.runtime.Quarkus.run(Quarkus.java:143)
at io.quarkus.runner.GeneratedMain.main(Unknown Source)
at java.base/jdk.internal.reflect.DirectMethodHandleAccessor.invoke(DirectMethodHandleAccessor.java:104)
at java.base/java.lang.reflect.Method.invoke(Method.java:565)
at io.quarkus.runner.bootstrap.StartupActionImpl$1.run(StartupActionImpl.java:156)
at java.base/java.lang.Thread.run(Thread.java:1474)
Caused by: java.lang.IllegalArgumentException: URLDecoder: Incomplete trailing escape (%) pattern
at java.base/java.net.URLDecoder.decode(URLDecoder.java:219)

In our case we pass connection string such as: mongodb://%s:%s@x.y.z.w.... as we use that as template to replace it with username & password to get the final connection string that is then passed to the manually constructed client (MongoClientSettings settings = MongoClientSettings.builder().applyConnectionString()...).

Is this expected behavior? We can do a workaround, but from the documentation I thought that feature would enable us to use the connection-string property.

[quarkus-bot[bot]]

/cc @loicmathieu (mongodb)

[mg1986jp]

This looks like a bug. When active: false is set, the MongoDB client creation should be skipped entirely — including connection string parsing. The fact that it still tries to URL-decode the connection string template (mongodb://%s:%s@...) and fails on the %s placeholders means the deactivation check happens too late in the startup sequence.

The relevant code path is in MongoClientRecorder where connection string parsing happens during build time (or early runtime), before the active/inactive check is evaluated. The active config was added in PR #51013 but it gates the client creation, not the config validation.

Workaround 1: Use a valid placeholder connection string that passes URL parsing:

quarkus.mongodb.connection-string=mongodb://placeholder:placeholder@x.y.z.w:27017/db
quarkus.mongodb.active=false

Then replace it at runtime when constructing your manual client.

Workaround 2: Use an environment variable with a valid default:

quarkus.mongodb.connection-string=${MONGODB_URI:mongodb://localhost:27017}
quarkus.mongodb.active=false

The default value passes parsing, and your application code uses the real templated URI when building the manual MongoClient.

Workaround 3: Use a profile-based config to avoid the property entirely in dev/test:

# application.properties
%prod.quarkus.mongodb.connection-string=${MONGODB_URI}
%prod.quarkus.mongodb.active=false

# In dev/test, don't set the property at all

This is likely worth filing as a bug — the expectation from the docs is that active: false should skip all processing of the client config, including validation. The fix would be to move the active check earlier in MongoClientBuildStep so it short-circuits before connection string parsing.

[cescoffier]

Yes, can you open an issue with your analysis?

[mg1986jp]

@cescoffier Done — #54476

[MILLERMARRU]

This is indeed a bug — the connection string is parsed before the active flag is evaluated. A practical workaround while this is resolved upstream:

Option 1: Provide a syntactically valid placeholder

quarkus.mongodb.active=false
quarkus.mongodb.connection-string=mongodb://localhost:27017

Even if the server does not exist, the string parses correctly and no connection pool is initialized when active=false. This avoids the %s placeholder parse error.

Option 2: Use profiles to exclude the config entirely

# Only define the URI in profiles where MongoDB is actually used
%prod.quarkus.mongodb.connection-string=${MONGO_URI}
%dev.quarkus.mongodb.connection-string=mongodb://localhost:27017

When the profile does not define the property, it will not be parsed at all.

Worth opening an issue if one does not exist yet — the expected behavior when active: false is set should skip all connection string validation.