Skip to content
javahacks.dev
Micronaut

Micronaut 3 to 4 Migration Steps and Breaking Changes

Migrate Micronaut 3 to 4: move to Java 17, rename javax to jakarta, update the parent and plugins, fix removed APIs, test and check native builds.

6 min read
Summarize in AI
Flat illustration of a staircase from one version to the next, with the OpenJDK and Apache Maven logos.

Moving Micronaut 3 to 4 is a platform upgrade. The framework model is the same, and the underlying versions and packages changed. Do it in small commits so a failure points to its cause. What is new is summarized in Micronaut 4 features.

Step 1: prepare on 3.x

  1. Update to the latest 3.x release and fix compiler and runtime deprecation warnings.
  2. Make sure the test suite passes. A green baseline matters here.
  3. Update the JDK to 17 or 21 and rebuild on Micronaut 3. If this fails, you have a JDK problem, not a Micronaut one, see UnsupportedClassVersionError.

Step 2: change the Micronaut version

Maven:

XML
<parent>
  <groupId>io.micronaut.platform</groupId>
  <artifactId>micronaut-parent</artifactId>
  <version>4.7.6</version>
</parent>

Gradle:

groovy
plugins {
    id("io.micronaut.application") version "4.4.4"
    id("io.micronaut.aot") version "4.4.4"
}

Use current versions from the Micronaut release page. The parent POM or the Gradle plugin supplies the BOM, so most module versions follow automatically. Update any explicit module versions you declared by hand.

Step 3: javax to jakarta

java
// before
import javax.inject.Inject;
import javax.inject.Singleton;
import javax.validation.constraints.NotBlank;
import javax.persistence.Entity;

// after
import jakarta.inject.Inject;
import jakarta.inject.Singleton;
import jakarta.validation.constraints.NotBlank;
import jakarta.persistence.Entity;

Do a project-wide replacement, then compile. For a large codebase use an automated recipe like OpenRewrite. Libraries on the classpath that still use javax need Jakarta versions too, a pattern explained in javax to jakarta errors.

Step 4: module changes

Some modules were renamed or restructured:

  • Micronaut Data: the repository API is the same, with updated artifacts.
  • HTTP client: the new client has the same declarative API. Custom filters should be re-checked.
  • Serialization: if you rely on Jackson databind, add micronaut-jackson-databind explicitly where required, or move to Micronaut Serialization.
  • Test: @MicronautTest still comes from micronaut-test-junit5, with changes to mocking annotations and property sources.

Step 5: compile and fix

Compile and read errors in order. Typical fixes are:

  • Removed classes and methods listed under "Breaking changes" in the guide.
  • Annotation processor path in Maven needs the 4.x processors.
  • Changed defaults, such as the property names for server and client timeouts.
  • Code relying on deprecated reflection-based features.

Step 6: test and verify

Shell
./mvnw clean verify

Then run the integration tests with real infrastructure and exercise the main user journeys in a staging environment. Look for differences in JSON output, header handling, error responses and timeouts. If you produce a native image, rebuild it and run the same tests against the native executable, since reflection and resource metadata can differ, as covered in native image builds.

Consider virtual threads

After the upgrade works, evaluate virtual threads on Java 21 for blocking code. It is a performance decision, not part of the migration, so measure first.

Inventory what the move touches

Micronaut 4 changes the baseline Java version to 17, replaces the javax packages with jakarta, and moves several modules. Count what your code uses before choosing a schedule.

Shell
java -version                                                                    # must be 17 or later for 4.x
grep -rn --include='*.java' --include='*.kt' -E 'import javax\.(inject|annotation|validation|persistence|transaction)' src | wc -l
grep -rn --include='*.java' --include='*.kt' -c 'io.micronaut.http.client.RxHttpClient' src | grep -v ':0'
grep -n 'micronaut' pom.xml build.gradle* 2>/dev/null | head -20

The first count is the size of the javax to jakarta rename. The second finds uses of removed client types; Micronaut 4 dropped the RxJava 2 based RxHttpClient, so those call sites need HttpClient with Reactor or blocking calls. The third lists the module coordinates you must align. A project with many javax.inject.Inject imports is a mechanical change, and one with its own RxJava code is a design change.

Change the version and let the build tell you the rest

Change the parent or BOM version first and compile. The compiler's error list is your to-do, and the first errors are nearly always the package renames. In Gradle:

build.gradlegroovy
plugins {
    id("io.micronaut.application") version "4.4.x"
    id("io.micronaut.aot") version "4.4.x"
}

micronaut {
    version("4.7.x")
    runtime("netty")
    testRuntime("junit5")
    processing { incremental(true); annotations("dev.javahacks.*") }
}

Use the 4.x plugin and Micronaut versions listed in the current release notes in place of x; the plugin version and the framework version are separate numbers. Micronaut resolves annotation processors at compile time, so a version mismatch between the processor and the runtime shows up as compile errors that mention missing generated classes.

Rename the injection and validation packages

The Jakarta rename covers @Inject, @Singleton, @PostConstruct and Bean Validation constraints. A script handles it, and a second check proves nothing was left behind.

Shell
git grep -l 'javax\.' -- '*.java' '*.kt' | xargs perl -pi -e 's/\bjavax\.(inject|annotation|validation|persistence|transaction)\b/jakarta.$1/g'
git grep -n 'javax\.' -- '*.java' '*.kt' '*.xml' '*.yml'

Anything still printed by the second command is either a JDK package, such as javax.net.ssl, which stays, or a place the pattern missed. Check the Micronaut data and validation modules by name, since the validation module changed its artifact to micronaut-validation with annotation processing, and an old reference to the Hibernate Validator integration no longer applies.

Check the behaviours that changed quietly

Three behaviours differ without compile errors. JSON serialization: new projects use Micronaut Serialization instead of Jackson by default, and fields that relied on Jackson annotations or reflection need @Serdeable. Test every response body with a JSON assertion and not only status codes. The threading rules for controllers: Micronaut 4 selects the thread for a controller method automatically from its return type, where 3.x defaulted to manual selection, so check the micronaut.server.thread-selection setting and review any handler that blocks. And configuration property names that were renamed in modules; start the application with micronaut.env.deduction=false and read the warnings in the log.

java
@Controller("/orders")
class OrderController {

    @Get("/{id}")
    @ExecuteOn(TaskExecutors.BLOCKING)       // explicit and harmless in 4.x, required under manual selection in 3.x
    OrderView get(long id) { return orders.find(id); }
}

A smoke test that calls each endpoint with realistic data, comparing the JSON with the output of the 3.x build, finds serialization differences before users do. Keep both builds deployable until the comparison passes, and roll out the new version to a fraction of traffic first.

Roll the migration out safely

Release the migrated service behind a flag or a canary rather than all at once. Route a small share of traffic to the Micronaut 4 build, compare error rates and latency with the 3.x build over a full business cycle, and keep the older build deployable. Pay attention to start-up time and memory, which usually improve, but verify on your workload: measure both builds with the same load and record the numbers in the change request. Update the container base image to a JDK 17 or later runtime in the same release so that the rollback path is one image tag, and remove the old build only after a release cycle without incident.

Where this does not apply

If you are still on Micronaut 2 or earlier, move to 3 first and follow the guides in order. The relevant section of the build is explained in the Micronaut tutorial. The reference is the Micronaut 4 migration guide, and the Micronaut project on GitHub lists the release notes.

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.