Micronaut 4 New Features Explained for Java Developers
What Micronaut 4 changed: a Java 17 baseline, the Jakarta namespace, a new HTTP client, virtual threads, Micronaut Serialization and a refreshed core.

Micronaut 4, released in 2023, is a platform release. It does not change what the framework is for: fast startup and low memory through compile-time processing. It updates the foundation. This post summarizes the changes a Java developer notices. The steps for an upgrade are in migrating Micronaut 3 to 4.
Java 17 and Jakarta
The minimum JDK is 17, and javax.* packages became jakarta.*, in line with Jakarta EE 9 and later, the background in the javax to jakarta change:
// Micronaut 3
import javax.inject.Singleton;
// Micronaut 4
import jakarta.inject.Singleton;Annotations for injection, validation and persistence use the new names. The change is mechanical and well suited to search and replace.
A new HTTP client and server core
The HTTP client was rewritten with a smaller footprint and better throughput, and it now supports HTTP/2 and HTTP/3 preview options more cleanly. The declarative client style stays:
@Client("https://api.example.com")
interface PriceClient {
@Get("/prices/{sku}")
PriceView get(String sku);
}The server core was reworked too: fewer layers between Netty and your controller, and an option for a thread-per-request model on virtual threads.
Virtual threads
On Java 21 or later, Micronaut can run blocking controller code on virtual threads:
micronaut.server.thread-selection=AUTO
micronaut.executors.blocking.type=virtualWith virtual threads, a blocking JDBC call no longer needs a reactive wrapper to scale, and simple imperative code becomes viable at high concurrency. The language feature behind it is covered in the modern Java guide. Thread-pinning with synchronized and native code still applies.
Micronaut Serialization
A compile-time serializer, with no reflection, is a supported replacement for Jackson databind, and native-friendly. See using Micronaut Serialization for the annotation and its limits.
Compile-time processing, extended
Micronaut 4 generates code with the Java annotation processor and with a source-level processing framework, with less bytecode manipulation than in version 3. Builds are more predictable, with clearer errors. Introspection is used in place of reflection for bean properties, which helps GraalVM native images. The dependency injection model is unchanged, as explained in compile-time DI.
Other changes you may notice
- Removal of APIs that were deprecated in 3.x.
- Updated Netty and Reactor versions.
- Improved GraalVM metadata and support for building native images with the Gradle or Maven plugin.
- A reorganized Micronaut Test that works with JUnit 5 as before, see MicronautTest.
- New module versions for Data, Security and Kafka. The security module's configuration is in JWT security.
Should you upgrade
If you are on Micronaut 3, the upgrade is mostly renames and version bumps, with a few behaviour changes. Support for Micronaut 3 ended, so security and bug fixes only land in the newer line. For a new project there is nothing to decide, start on the current release.
What the code looks like now
A controller in Micronaut 4 uses the Jakarta namespace for validation and injection, and the rest reads the same as before:
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;
import jakarta.validation.constraints.NotBlank;
@Controller("/greetings")
class GreetingController {
@Get("/{name}")
String greet(@NotBlank String name) {
return "Hello " + name;
}
}A project that still imports javax.validation or javax.inject does not compile after the upgrade. The jakarta imports are the most visible and most mechanical part of the change, and an automated search and replace of the prefix handles them for the Jakarta EE packages. Do not replace javax.sql or javax.crypto, which stay in the JDK.
Build tool setup
The Gradle plugin is io.micronaut.application version 4.x, and the Maven parent is micronaut-parent version 4.x. Both set the compile target to Java 17, and both configure the annotation processors that do the compile-time work. A build that lists processors by hand, a common leftover from older projects, needs them checked, because the processor artifacts were renamed and reorganized in the platform. When the generated classes are missing at runtime, with errors such as NoSuchBeanException for a bean that is plainly annotated, the processor did not run. Look for the processors in the build output first.
Testing with the new baseline
Micronaut 4 tests use JUnit 5 with @MicronautTest, and the old Spock and JUnit 4 integrations need their own updated modules. The test annotation starts the application context once per class by default:
@MicronautTest
class GreetingControllerTest {
@Inject
@Client("/")
HttpClient client;
@Test
void greets() {
String body = client.toBlocking().retrieve("/greetings/Ada");
assertEquals("Hello Ada", body);
}
}A test suite that passes before and after the upgrade is the best evidence that behaviour held. Run it on the old version first and record the result, so a failure afterwards is a change and not a pre-existing problem.
Effort by area
The work an upgrade takes depends on what the application uses beyond controllers and beans.
| Area | Effort | What to check |
|---|---|---|
| Controllers, services, beans | Low | Imports, compile |
| Declarative HTTP clients | Low to medium | The @Client API stayed, filters and error types changed |
| Data access | Medium | Micronaut Data and the Hibernate version it brings |
| Custom filters and interceptors | Medium | Types in the HTTP layer moved, read the migration notes |
| Security | Medium | Configuration properties and the SecurityRule API |
| Native image | Medium | Reflection configuration, GraalVM version |
| Third-party modules | Varies | Each one needs a release for Micronaut 4 |
The last row is the one that blocks projects. A module with no Micronaut 4 release has to be replaced, forked or kept in a service that stays on the old version. Check every dependency before committing to a date.
What does not change
Dependency injection resolved at compile time, no reflection at startup, and small memory use remain the reasons to use the framework. A service that runs well on version 3 gains little in raw speed from 4, and the case for upgrading rests on support, the Java 17 baseline, virtual thread support and staying on a line that gets security fixes. Version 3 stops receiving fixes, so a long-lived service has a deadline, and the earlier the migration starts, the smaller the jump from the platform's next release.
What to tell the team before the upgrade
An upgrade goes better when the team knows what to expect. Share three things: the list of dependencies that need a new release and their status, the expected changes to imports and build files, and the plan for the test run on the old version, which gives the baseline. Agree on a short freeze for other changes to the build during the work, since a parallel change to the same files turns a day of work into a week.
Afterwards, record what took the time. The note is the best estimate for the next major upgrade, and it shows which parts of the application cost the most to keep current.
Where this does not apply
Micronaut 4 does not make a blocking service reactive or turn Java into Kotlin. A comparison of the framework against others is in Micronaut versus Spring Boot. The reference is the What's new in Micronaut 4 page, and the Micronaut documentation lists every module.


