Quarkus 3.21.3 Maintenance Release

A quick overview of the changes and dependency updates.

The Quarkus team released 3.21.3 today and I thought it might be worthwhile to classify the changes a little and give you a more detailed look into the uncountable little changes that are called “maintenance”. You’ll be surprise to what length the team goes to make sure you have everything working smoothly.

Quarkus 3.21.3 focuses on stability and polish, delivering a broad set of bug fixes across multiple areas of the framework. These improvements target better reliability, developer experience, and integration consistency. The following sections group the main fixes by category:

Key Categories and fixes

Native Image Build Stability and Compatibility

Quarkus is built with native image compilation in mind, making GraalVM support a key priority. This release includes targeted fixes to improve build reliability and compatibility across various environments:

• Hardware/OS Specific Fixes: Several fixes directly address build failures encountered on specific, modern developer platforms. Issues #46235 and #46988 resolved native image build failures specifically reported on aarch64 macOS (commonly found on Apple M1/M2 hardware) when using recent GraalVM versions. The inclusion of these fixes highlights the project's responsiveness to the evolving hardware landscape used by developers. As adoption of platforms like Apple Silicon Macs increases, subtle incompatibilities with complex toolchains like GraalVM native compilation can emerge. Addressing these promptly in a maintenance release prevents developers using these common setups from being blocked.

• Feature Clarification: Pull request #46731 added clarification that native-image's ForeignAPISupport is currently limited to the amd64 architecture. While not a bug fix per se, managing expectations about platform-specific native features contributes to a better developer experience by preventing confusion or attempts to use unsupported capabilities.

Developer Experience (DevEx) and Tooling

Quarkus continues to invest in productivity features like Dev Mode, Dev UI, and seamless build tool support. This release brings several refinements that streamline the development workflow:

• Dev Mode and Configuration: Issue #46718 fixed a problem where quarkus.application.version failed to resolve correctly in dev mode. Furthermore, #47176 ensured build properties are correctly propagated within the IDE DevMode context, improving consistency between build environments and IDEs.

• Dev Services Improvements (Keycloak OIDC): A notable cluster of fixes targets the Keycloak Dev Service, used for simulating OIDC environments during development. Issue #47102 resolved a startup failure when an OIDC client was configured in versions 3.20/3.21. Logging was improved for clarity (#47280, #47318), username handling was corrected to avoid appending @example.com if an email was already present (#47284, #47296), and the Keycloak container memory limit was increased (#47340). This focus indicates active refinement based on user feedback, ensuring this critical tool for security testing during development remains robust and user-friendly.

• Dev UI Enhancements: The Dev UI, a web-based console for inspecting application state, also received fixes. Issues #47304 and #47311 addressed problems in the Database view, ensuring UUID values are displayed correctly and data from all tables (not just the first) is shown. Agroal (connection pool) related fixes were also included (#47334). Additionally, a corrupted JAR dependency affecting Dev UI resources was fixed (#47277). These iterative improvements enhance the utility of the Dev UI for runtime inspection.

• Build and Test Tooling: Fixes were made to improve integration with build tools and testing workflows. Issue #47189 resolved a failure in the generate-code-tests phase when using JGitVer in multi-module projects. Loading of POM files manipulated by Maven extensions was corrected (#47375), and the set of system properties passed to test tasks was restricted (#47380), potentially improving test isolation.

Core Framework, CDI, and Configuration

Fixes addressing the fundamental mechanisms of the framework ensure overall stability and predictability:

• Classloading: Issues #46563 and #47378 corrected problems with resource path loading via RunnerClassLoader, specifically ensuring correct handling of trailing slashes, which can be crucial for locating resources correctly.

• CDI (Contexts and Dependency Injection): Several fixes targeted ArC, Quarkus's CDI implementation. Pull requests #47148 and #47244 clarified and enforced requirements for CDI Decorators, establishing that @Dependent scope is necessary and that @Decorator itself is considered a bean defining annotation. Ambiguous bean resolution errors were fixed for specific scenarios involving ResteasyReactiveCommonRecorder (#47107) and sub-resource interfaces with multiple implementations (#47197). These corrections prevent potentially hard-to-debug dependency injection failures.

• Framework Robustness: Pull request #47283 added logic to reindex Jandex if the index appears newer than expected, improving resilience against potential build state inconsistencies.

• Documentation: A typo in the configuration mapping documentation for @WithParentName was corrected (#47257).

Data Persistence and Access

Stable and consistent access to data stores is essential. This release delivers focused fixes to improve reliability across persistence layers:

• Hibernate Reactive: Issue #46917 corrected a problem where Hibernate Reactive was eagerly fetching incorrect records for ManyToOne relationships, ensuring data integrity in reactive applications.

• Hibernate ORM: Pull request #47305 disabled checks related to unsupported bytecode enhancement features, likely as a pragmatic adjustment to recent changes or limitations in the enhancement process, particularly noted as failing for value classes in #47286.

• MongoDB Liquibase: For users employing Liquibase with MongoDB, issue #46998 fixed a problem where nested ChangeLog files were not being picked up correctly in native mode when using the includeAll directive.

Web Layer (REST, WebSockets)

Improvements were made to components handling web interactions:

• WebSockets Next: Issues #47235 and #47271 addressed problems with the WebSocket Next auto-ping timer. One fix prevents logs from filling up with "Unable to send auto-ping... WebSocket is closed" messages, and the other corrects the timer's behavior.

• REST Client: Pull requests #47360 and #47368 fixed the handling of java.util.Optional<> types when used as @HeaderParam arguments in the typesafe REST Client, allowing for more idiomatic API definitions.

Testing Framework

Ensuring developers can reliably test their applications is crucial. Several fixes targeted the testing infrastructure:

• JUnit 5 Integration: Issues #47275 and #47281 resolved problems that prevented standard JUnit 5 @Nested tests from working correctly with @QuarkusComponentTest. This was due to unexpected CDI bean removal during compilation, and proper cleanup for nested classes was also implemented. These fixes ensure that developers can use common JUnit patterns seamlessly with Quarkus's component testing support.

• Test Resource Injection: Issues #47369 and #47373 corrected the behavior of @TestHTTPResource injection when the quarkus.http.root-path configuration property is set to a value that doesn't start with a forward slash. This ensures test utilities work correctly regardless of common application path configurations.

Key Dependency Updates

As expected for a maintenance release, Quarkus 3.21.3 includes several patch-level dependency updates. These updates bring in bug fixes, security improvements, and minor enhancements from upstream libraries, all while avoiding breaking changes. Keeping dependencies current is part of routine framework maintenance, ensuring stability and alignment with supported versions.

The notable dependency updates included in this release are :

• io.smallrye.common:smallrye-common-bom updated from 2.10.0 to 2.11.0 (#47054)

• Hibernate Reactive updated from 2.4.5.Final to 2.4.6.Final (#47251)

• com.google.guava:guava updated from 33.4.6-jre to 33.4.7-jre (#47261)

• org.mvnpm.at.mvnpm:qomponent (Dev UI component) updated from 1.0.3 to 1.0.4 (#47297)

• org.junit:junit-bom updated from 5.12.1 to 5.12.2 (#47322, #47330)

• org.apache.commons:commons-text updated from 1.13.0 to 1.13.1 (#47329)

• io.micrometer:micrometer-bom updated from 1.14.5 to 1.14.6 (#47362)

How to Update

To update to Quarkus 3.21, the team recommends updating to the latest version of the Quarkus CLI and run:

quarkus update

Note that quarkus update can update your applications from any version of Quarkus (including 2.x) to Quarkus 3.21.

For more information about the adjustments you need to make to your applications, please refer to the Quarkus 3.21 migration guide.