Axon 4 to Axon 5 Upgrade

Axon Framework 5 represents the most significant evolution in the framework’s history. This comprehensive upgrade guide will help you navigate the transition from Axon Framework 4.x to Axon Framework 5, equipping you with the knowledge, patterns, and practical steps needed to modernize your event-sourced applications successfully.

Whether you’re running a small microservice or a large distributed system, this guide provides pathways for every scenario—from maintaining compatibility with your existing architecture to embracing the transformative new capabilities that Axon Framework 5 enables.

What You’ll Find in This Guide

This upgrade guide is structured as follows:

Staged upgrade plan

Follow the upgrade from an existing Axon Framework 4 application through code conversion and, where needed, DCB, legacy saga compatibility, and workflows. Each stage links to its documentation, agent skills, and tooling, with checks to complete before continuing.

Why Upgrade to Axon Framework 5

Before you commit to the upgrade, understand what you’re gaining. This section explores the transformative new capabilities available only in Axon Framework 5: async-native architectures that eliminate ThreadLocal bottlenecks, Dynamic Consistency Boundaries (DCB) that liberate you from fixed aggregate structures, simplified configurations that adapt to your preferences, domain entities free from framework annotations, and a thriving ecosystem of first-class extensions like the Apache Kafka and PostgreSQL integrations.

Prerequisites & System Requirements

Verify your infrastructure readiness. We cover Java version alignment, Spring Boot compatibility, and Axon Server requirements to ensure a smooth upgrade.

Automated Code Conversion

Get a head start with OpenRewrite-based recipes that mechanically rewrite the predictable parts of your Axon Framework 4 codebase. Running them does not guarantee a compiling project—the compile errors that remain, together with axon4to5 markers left in the source, become your guided checklist for the manual steps. Code conversion covers only source and build file transformations; it does not touch event store data, token tables, or any other runtime state.

Application Design Problems Solved by Axon Framework 5

Understand the "why" behind each major change. We walk through the application design problems that Axon Framework 5 solves, the architectural philosophy driving those solutions, and how they cascade through your codebase.

Understanding the Architecture Principles of Axon Framework 5

Detailed explanations of how foundational components have evolved, providing a conceptual background how we adjusted the architecture principles for Axon Framework 5.

Upgrade Paths

The practical heart of the guide. Acts as the starting point for every code upgrade from Axon Framework 4 to Axon Framework 5. Contains numerous subsections (or "paths") showing how Framework 4 approached things like messaging, aggregates, and testing, and how those should be tackled in Axon Framework 5.

Staged upgrade plan

Choose the upgrade route

  • Framework upgrade: complete the baseline and code upgrade stages, plus the legacy saga stage if the application uses sagas. An Axon Framework 5 application can retain aggregate-based storage; DCB conversion is optional for this route.

  • Saga to workflow: also complete the DCB stage for the Axon Server workflow route, then introduce workflows alongside existing sagas and retire the legacy code after it drains.

  • Already on Axon Framework 5: verify the completed stages and start at the first remaining stage.

The stages describe separate work packages, not necessarily separate deployments. For an application with sagas, complete the code upgrade and legacy saga adaptation before its first Axon Framework 5 deployment. Complete context conversion before deploying an application configured with a DCB event storage engine. Context conversion can also precede the code upgrade while a compatible Axon Framework 4 application is still running.

Stage Documentation Agent skill or tooling

0. Establish the baseline

Prerequisites

Existing application tests and a representative persisted-data copy

1. Axon 4 to Axon 5 code

OpenRewrite code conversion and component upgrade paths

axon4to5-openrewrite, then axon4to5-migrate-code; OpenRewrite recipes

2. Regular context to DCB context

Event storage engine selection and Axon Server context upgrade

Axon Server upgrade UI or REST API; no OpenRewrite recipe

3. Axon 4 sagas to Axon 5 legacy sagas

Legacy saga upgrade

axon4to5-migrate-code saga recipe; Axon4ToAxon5Legacy within the OpenRewrite upgrade recipes

4. Sagas to workflows with coexistence

Legacy sagas to workflows

saga-to-workflow; behavior-driven implementation and tests

5. Retire legacy sagas

Retirement checks

saga-to-workflow; drain verification and application-specific cleanup

Install the skills from Axoniq Agent Skills. That repository owns the skill instructions and supporting resources. OpenRewrite owns mechanical source transformations; neither OpenRewrite nor the code upgrade skill modifies runtime data.

Stage 0: Establish the baseline

Record the application’s Framework, Java, Spring Boot, Axon Server, and extension versions. Check prerequisites against the selected target release. Inventory the following before changing the application:

  • Modules, commands, queries, event handlers, serialization formats, and stored event revisions.

  • Event storage engines, context names, event processor names, tracking tokens, and dead-letter queues.

  • Saga types, associations, serialized state, deadlines, and the number of running instances per saga type.

  • Existing behavior tests, schema upgrade scripts, backups, and recovery procedures.

Completion check: the existing application passes its tests and resumes representative persisted processes after a restart. Use a copy of production-like state to verify subsequent stages, including an instance waiting for an event and one waiting for a deadline.

Stage 1: Axon 4 to Axon 5 code

It is strongly recommended to run the OpenRewrite conversion on a working copy with a recoverable baseline. Otherwise, you will have to process all the paths manually to ensure your Axon Framework 4 code is updated to Axon Framework 5. Assuming you’re following the OpenRewrite approach, choose the recipe for the selected Framework distribution:

  • org.axonframework.migration.UpgradeAxon4ToAxon5 for the open-source Framework route.

  • io.axoniq.framework.migration.UpgradeAxon4ToAxoniq5 for the Axoniq route, including applications using Axon Server or the legacy saga module.

Both recipes are distributed in org.axonframework:axon-migration:<version> from the Axon Framework upgrade module. The module also supplies the Gradle initialization script. The axon4to5-openrewrite skill runs the automated part; pass --recipe-version <version> to select the recipe release instead of its bundled default. The axon4to5-migrate-code skill handles the remaining component changes. The axon4to5-isolatedtest skill supports scoped verification during that work.

Review compiler errors and every TODO(axon4to5) marker. Apply the relevant upgrade paths, including serialization, token storage, and event processors. Verify dependency coordinates against the selected release rather than assuming the recipe output is complete.

Completion check: application code and tests compile, behavior tests pass, and persisted events and processor tokens remain readable. For applications with sagas, include stage 3 in this check before deployment. If the application uses a DCB engine, also complete stage 2 first.

Stage 2: Regular context to DCB context

This stage applies when moving an Axon Server context to Dynamic Consistency Boundaries (DCB), including the workflow route in this guide. To upgrade the Framework while retaining a regular context, use AggregateBasedAxonServerEventStorageEngine as described in event store upgrade and defer this stage.

Follow the version-specific Axon Server context upgrade procedure. It covers preparation, completion, cleanup, permissions, and restrictions on the source context. Schedule the completion step for an interruption: the context is temporarily unavailable during the switch. If Axon Framework 4 clients continue to use the context, upgrade them to 4.13.2 or higher to ensure compatibility.

Verify snapshot compatibility for the selected engine and Framework release; see snapshot upgrade. Include entity reconstruction from historical event streams in the verification.

Completion check: the server reports a DCB context, historical events remain readable, and the application continues processing from its retained tokens. Verify each context used by the workflow and the storage engine configured for it.

The Axon Server upgrade tool copies events from other event stores or Axon Server instances. It does not perform regular-context-to-DCB conversion. Use it only if moving event-store data is a separate requirement of the upgrade.

Stage 3: Axon 4 sagas to Axon 5 legacy sagas

Use the legacy saga upgrade path to run existing sagas on the selected Axoniq Framework release. The OpenRewrite upgrade includes org.axonframework.migration.Axon4ToAxon5Legacy for mechanical saga changes. Finish the remaining handler injection, configuration, and test changes with axon4to5-migrate-code.

Preserve saga type identities, serialized payloads, association values, and the existing processor identity and tracking positions. Keep the same value when changing @ProcessingGroup to @Namespace. Resolve deadline behavior explicitly: a removed deadline or a commented-out handler is not a completed upgrade. When the selected legacy release does not support an existing deadline mechanism, implement and test its replacement or drain the affected instances before cutover.

Completion check: an instance created on Axon Framework 4 loads and advances on Axon Framework 5 without being recreated. Verify success, failure, pending deadlines, and restart behavior against persisted state. New instances may still start as legacy sagas at this stage.

Stage 4: Sagas to workflows with coexistence

Start this stage after the application runs on the target Framework release and its workflow event storage is ready. Follow Legacy Sagas to Workflows for the process diagram, behavior conversion, verification, and coexistence procedure. Use the saga-to-workflow skill for implementation support. Existing instances finish as sagas; new instances start as workflows at a verified cutover boundary.

Completion check: an old saga completes, a new workflow completes, and a restart resumes both from durable state. See the persistent coexistence checks.

Stage 5: Retire legacy sagas

Follow the legacy saga retirement procedure after running instances and their pending work have drained. Remove only unused legacy code, dependencies, and dedicated storage; preserve shared token tables and unrelated processor progress.

Completion check: a fresh workflow completes and a running workflow resumes after a restart without the retired legacy runtime.

Scope of this guide

This guide assumes you’re running Axon Framework 4.x and moving to Axon Framework 5. We focus on:

  • Applications using Spring Boot or standalone Java

  • Event sourcing patterns with aggregates (or entities with DCB!)

  • Synchronous and reactive command/query patterns

  • Integration with Axon Server

  • Testing strategies and fixtures

For questions about topics outside this scope, consult the Axon Framework documentation, reach out on the Axon Community Forum, or contact AxonIQ support.