Clarification needed: Are some "fixed at build time" options overridable?

[svifred]

The configuration reference states, that providing a value for quarkus.http.host is required. At the same time, a default value of either localhost or 0.0.0.0 is provided depending on the active profile:

I expect the "required with default provided" to work in the following way:

1. Providing no value is valid, as default value is used.
2. Providing non-empty value is valid.
3. Providing empty value is invalid.

I further expect "fixed at build time" to mean, that setting the value can only happen before the Quarkus-application is built, but an environment variable is available for overriding the property. Setting that variable or using a system property, i.e. using JAVA_OPTS to set -Dquarkus.http.host=<some-ip>, the value provided at build time is overridden (whether build time value was provided directly or was not provided and default used).

My question is: How should I interpret the documentation, when a configuration property is marked all of

• required
• with default value
• fixed at build time
• overridable by environment variable

[svifred]

(Deleted when above question was rephrased.)

[cescoffier]

\CC @radcortez

[radcortez]

expect the "required with default provided" to work in the following way:

1. Providing no value is valid, as default value is used.
2. Providing non-empty value is valid.
3. Providing empty value is invalid.

Correct. In this case, the docs are a bit misleading due to a limitation in our code. Usually, the docs take the value from @WithDefault in the configuration object, but because quarkus.http.host has different defaults depending on the profile, we cannot use a static value default value. The documentation processing handles these cases as if there is no default, so it is marked as required. I'll think of a way to improve the situation.

I further expect "fixed at build time" to mean, that setting the value can only happen before the Quarkus-application is built, but an environment variable is available for overriding the property. Setting that variable or using a system property, i.e. using JAVA_OPTS to set -Dquarkus.http.host=<some-ip>, the value provided at build time is overridden (whether build time value was provided directly or was not provided and default used).

Fixed at build time means that the configuration is read during the build and has no effect during runtime. Overriding such a property results in a warning such as:

Build time property cannot be changed at runtime:
 - quarkus.http.root-path is set to 'x' but it is build-time fixed to '/'. Did you change the property quarkus.http.root-path after building the application?

Environment variables or system properties can be used during the build to set build-time properties.

My question is: How should I interpret the documentation, when a configuration property is marked all of

• required

The configuration must be specified in a valid source. The source must be available in the appropriate phase (build or runtime). These are exceptions due to the limitations explained previously.

• with default value

The default value is the actual configuration value if no other value has been set in the configuration.

• fixed at build time

These configuration can only be set during the build and are ignored at runtime.

• overridable by environment variable

Configurations are overridden depending on where they are set. Quarkus orders each source by ordinatily, and the first source to contain the configuration wins. Please check: https://quarkus.io/guides/config-reference#configuration-sources.

An environment variable is not the only way to override a configuration, but the name is included in the docs, because the defined dotted name and its environment variable name might have slight differences. Please check: https://quarkus.io/guides/config-reference#environment-variables

[svifred]

Thank you for confirming our expectations. And sorry, I was unclear: We are providing quarkus.http.host at runtime which unexpectedly does not result in an error.

To reproduce:

$ quarkus create app --gradle
$ cd code-with-quarkus/
$ ./gradlew build
$ java -jar build/quarkus-app/quarkus-run.jar
__  ____  __  _____   ___  __ ____  ______
 --/ __ \/ / / / _ | / _ \/ //_/ / / / __/
 -/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \
--\___\_\____/_/ |_/_/|_/_/|_|\____/___/
2025-09-24 20:08:47,679 INFO  [io.quarkus] (main) code-with-quarkus 1.0.0-SNAPSHOT on JVM (powered by Quarkus 3.28.1) started in 1.462s. Listening on: http://0.0.0.0:8080
2025-09-24 20:08:47,694 INFO  [io.quarkus] (main) Profile prod activated.
2025-09-24 20:08:47,694 INFO  [io.quarkus] (main) Installed features: [cdi, rest, smallrye-context-propagation, vertx]
2025-09-24 20:08:53,475 INFO  [io.quarkus] (main) code-with-quarkus stopped in 0.047s

So far, so good: As no value was provided for quarkus.http.host, Quarkus uses the default value and binds to http://0.0.0.0:8080.

As stated:

• fixed at build time
  These configuration can only be set during the build and are ignored at runtime.

We expect providing a value for quarkus.http.host on the command line when starting the already built Quarkus application to result in

• an error like Build time property cannot be changed at runtime
• Quarkus binding to 0.0.0.0 regardless of value given runtime.

It does neither:

$ java -Dquarkus.http.host=255.255.255.255 -jar build/quarkus-app/quarkus-run.jar
__  ____  __  _____   ___  __ ____  ______
 --/ __ \/ / / / _ | / _ \/ //_/ / / / __/
 -/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \
--\___\_\____/_/ |_/_/|_/_/|_|\____/___/
2025-09-24 20:09:13,455 ERROR [io.qua.run.Application] (main) Unable to bind to host: 255.255.255.255 and port: 8080.

Quarkus apparently readily accepts the runtime override of the fixed at build time property quarkus.http.host (and fails to bind to the obviously wrong address).

Now, it does seem reasonable, that the address should be overridable when given before startup of the HTTP server, but it is unexpected when reading the documentation - at least it is unexpected for me 😊

[radcortez]

I'm sorry, I was not clear about quarkus.http.host, and I explained the general rules of configuration.

The configuration quarkus.http.host is a runtime property, so this is the expected behavior. The configurations that are build-time are marked with a lock icon. For example, quarkus.http.root-path used in my previous comment:

[svifred]

Ah! I was simply mistaken in reading the docs and mixed-up the two 😅

Thanks for tasking you time to clear it up 😊