Quarkus Build Time Processing Explained With Examples
How Quarkus extensions run build steps, which configuration is fixed at build time, and what that changes about properties, profiles and library choices.

A Spring Boot application figures out what it is while it starts: it scans the classpath, reads annotations, evaluates conditions and builds the bean graph, every time the process launches. Quarkus moves almost all of that work to the build. By the time the jar exists, the decisions have been made, the classes generated and the framework's reflection replaced by plain calls. That is the reason a Quarkus service starts quickly and works in a native image, and it is also the source of a rule that surprises newcomers: some configuration cannot be changed after you build. This post explains how build-time processing works with the pieces you can see, shows the configuration that is locked in and the configuration that is not, what the runtime warning looks like when you get it wrong, and what this means for choosing libraries. Examples use Quarkus 3.x and JDK 25.
Two modules per extension
A Quarkus extension is split into two parts. The runtime module is what your application ships: the classes that run when requests arrive. The deployment module is what only the build uses: it inspects your code and the runtime module, decides what to generate and tells Quarkus what the application needs. The deployment code runs inside the Maven or Gradle build and never starts in production.
You can see the effect by looking at what the build leaves behind. After ./mvnw package, the application's classes include generated ones that you never wrote:
./mvnw package -DskipTests
unzip -l target/quarkus-app/quarkus/generated-bytecode.jar | grep -i -E 'bean|Client' | head -5 9215 io/quarkus/arc/setup/ArcContainerImpl.class
3340 org/acme/OrderResource_ClientProxy.class
2891 org/acme/OrderService_Bean.classOrderService_Bean is the generated class that creates an OrderService. In a reflection-based framework this would be code discovered at runtime; here it is bytecode written by the build, so at startup the container calls a known constructor and nothing needs to be looked up. The extension's deployment module declares build steps that produce this output. The shape of a build step is simple, and writing one is covered in the guide to writing extensions:
@BuildStep
FeatureBuildItem feature() {
return new FeatureBuildItem("my-feature");
}
@BuildStep
@Record(ExecutionTime.STATIC_INIT)
void registerBeans(MyRecorder recorder, BuildProducer<AdditionalBeanBuildItem> beans) {
beans.produce(AdditionalBeanBuildItem.unremovableOf(MyService.class));
}Build steps consume and produce build items, the framework orders them by those dependencies, and a recorder method is a way of saying "at runtime, call this method with these arguments" without the call happening during the build. You rarely write these. You do live with the consequences.
The index
To know what your application contains, the build needs a list of every class and its annotations, without loading them. Quarkus uses Jandex, an annotation index, for this. It indexes your application's classes automatically, and that explains one frequent surprise: a bean in a dependency jar is invisible unless that jar is indexed.
A library jar without a Jandex index or a beans.xml is skipped. You can ask Quarkus to index it:
quarkus.index-dependency.shared.group-id=dev.javahacks
quarkus.index-dependency.shared.artifact-id=shared-domainjakarta.enterprise.inject.UnsatisfiedResolutionException: Unsatisfied dependency for type dev.javahacks.shared.PriceCalculator and qualifiers [@Default]That exception, from an injection of a class that lives in an unindexed jar, is the symptom, and the cause is that the build never saw the bean. The diagnosis steps for related injection failures are in Quarkus unsatisfied dependency and ambiguous beans. Dependencies that are not in the index are also pruned: a bean nobody injects is removed from the container to save work, and @Unremovable stops that if you look beans up programmatically.
Three kinds of configuration
Because the build does the heavy work, each configuration property belongs to one of three groups, and the configuration reference marks every property with a lock icon for the first.
| Kind | When it is read | Can you change it at runtime? | Example |
|---|---|---|---|
| Build time | During package | No: needs a rebuild | quarkus.datasource.db-kind, quarkus.hibernate-orm.database.generation mode, quarkus.http.root-path for generated paths |
| Build time, read at runtime | Fixed at build, visible at runtime | No | The value is baked in; the property is shown for information |
| Runtime | When the process starts | Yes, by environment, system property or file | quarkus.datasource.jdbc.url, quarkus.http.port, quarkus.log.level |
Two properties of the same extension sit in different columns: the database kind decides which driver code is included in the build, so it is fixed. The URL, username and password are only values, so they stay free. The reasoning is that a decision that changes which classes are generated cannot wait for runtime, because there is no runtime code generation.
What happens when you change a locked property after the build? Quarkus checks at startup and warns:
java -Dquarkus.datasource.db-kind=postgresql -jar target/quarkus-app/quarkus-run.jarWARN [io.qua.config] Build time property cannot be changed at runtime:
- quarkus.datasource.db-kind was 'h2' at build time and is now 'postgresql'The application then runs with the build-time value, h2, and ignores your override. This is the dangerous half of the design: it is a warning, not a failure, and a deployment that sets a build-time property in an environment variable will happily start with the wrong behavior. Watch for that line in startup logs, and treat it as an error in your pipeline:
./run.sh 2>&1 | tee startup.log
grep -q 'Build time property cannot be changed at runtime' startup.log && echo "misconfigured" && exit 1Profiles and build-time values
Quarkus profiles (%dev, %test, %prod) pick values by name, and the profile active at build time matters. The package step builds with the prod profile unless told otherwise, so the build-time properties are the %prod ones, whatever you set when you run the jar.
quarkus.datasource.db-kind=postgresql
%dev.quarkus.datasource.db-kind=h2
%test.quarkus.datasource.db-kind=h2
quarkus.datasource.jdbc.url=jdbc:postgresql://${DB_HOST:localhost}:5432/shop
%dev.quarkus.datasource.devservices.enabled=trueHere the production build includes only the PostgreSQL driver code. Running that jar with -Dquarkus.profile=dev will not bring H2 back, because the code for it was not built in. To get a different behavior you build with a different profile: ./mvnw package -Dquarkus.profile=staging. The sibling issue, where a test uses a different build than production and therefore proves less, is why dev services run real containers of the production kind. You can inspect the effective value of every property, and which are build-time, with ./mvnw quarkus:info and the dev UI's configuration page.
What this means for library choices
Because Quarkus decides at build time, the libraries you pick fall into three groups.
Quarkus extensions. Written for build-time processing, they work in JVM and native mode, and their configuration follows the rules above. Prefer an extension when one exists; the work of making the library native-friendly has been done.
Plain Java libraries. They work on the JVM, since they are just jars. In a native image, anything they do with reflection, resources or dynamic proxies must be declared to the build, and when they are not, you get the failures in Quarkus native build failures with reflection. A library that scans the classpath at startup also defeats the point: it spends startup time Quarkus saved elsewhere.
Frameworks that assume a runtime container. A Spring library that relies on BeanPostProcessor and runtime classpath scanning will not work as is. Quarkus has Spring compatibility extensions for the common API surface, but you are better served by the native equivalents.
The consequence for design is mild but real: do not read configuration to decide which class to instantiate by name at runtime, use CDI producers and build-time conditions instead; keep reflection out of hot startup paths; and keep a native build in your CI so surprises show up on the branch. The payoff, quantified in why Quarkus starts fast, is a process that spends its startup budget serving requests rather than discovering what it is. Details of the properties are in the configuration reference.
Where build-time processing does not apply
Test and dev modes do not follow the same path: dev mode rebuilds incrementally as you save a file and restarts the application in-process, so a build-time property changes at the next reload without a manual rebuild, which hides the distinction until production. Runtime-only properties, such as credentials, ports and log levels, behave like any other framework's configuration. And for a service whose behavior must change per tenant or per request, build-time configuration is the wrong tool altogether, since those choices belong in application data or runtime configuration that you read on each call.


