Skip to content
javahacks.dev
Quarkus

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.

7 min read
Summarize in AI
Flat illustration of startup time of a JVM compared with a native image, with the Quarkus, OpenJDK, Spring Boot and Kubernetes logos.

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:

Shell
./mvnw package -DskipTests
unzip -l target/quarkus-app/quarkus/generated-bytecode.jar | grep -i -E 'bean|Client' | head -5
Text
 9215  io/quarkus/arc/setup/ArcContainerImpl.class
 3340  org/acme/OrderResource_ClientProxy.class
 2891  org/acme/OrderService_Bean.class

OrderService_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:

java
@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:

src/main/resources/application.propertiesproperties
quarkus.index-dependency.shared.group-id=dev.javahacks
quarkus.index-dependency.shared.artifact-id=shared-domain
Text
jakarta.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.

KindWhen it is readCan you change it at runtime?Example
Build timeDuring packageNo: needs a rebuildquarkus.datasource.db-kind, quarkus.hibernate-orm.database.generation mode, quarkus.http.root-path for generated paths
Build time, read at runtimeFixed at build, visible at runtimeNoThe value is baked in; the property is shown for information
RuntimeWhen the process startsYes, by environment, system property or filequarkus.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:

Shell
java -Dquarkus.datasource.db-kind=postgresql -jar target/quarkus-app/quarkus-run.jar
Text
WARN  [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:

Shell
./run.sh 2>&1 | tee startup.log
grep -q 'Build time property cannot be changed at runtime' startup.log && echo "misconfigured" && exit 1

Profiles 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.

src/main/resources/application.propertiesproperties
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=true

Here 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.

Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.