Event upcaster tutorial

Hi team,

I’m new to Axon framework.

Would it be possible to share some tutorial on Event Upcasting, I’m struggling in creating one.
I have an aggregate for phisical Users with several thousand of real users already joined and now I have to add business users with their business company names, addresses etc, which causes some major changes in the aggregate.

Would really appreciate.

Thanks you,

Hi Rashid,

I’d suggest you check out the Reference Guide on this topic, which you can find here.
From a tutorial perspective, you can follow the training we provide, which can either be on-site or as a public format.

If you have any question when implementing an Upcaster, feel free to drop them here.
But make them more specific than an entire tutorial.

If other attendees of the User group are willing to provide one, by all means.


Thanks Steven, I think that the Event Upcasting is one of the most frustrating parts of the Axon framework for beginners. If somebody could share a small primer, that would boost the usage of the framework.
Specific questions would follow based on that primer.


Hi Rashid,

It is undoubtedly a difficult thing to grasp, granted.
You might have seen the Quickstart Video series we have on YouTube.
I am playing with the idea to eventually provide more advanced videos as well, for example about Upcasters.

Until that video is in place, I do feel that the samples contained in the Reference Guide would be a fine “primer” as you call it.

If I’d make a recording out of building one, it wont deviate that much from those snippets.

Hence, I am not sure what more information you require in this area at this point, as there is not much else to it.

Kind regards,

Steven van Beelen

Axon Framework Lead Developer



Hello Steven,

I am having the same problem with the understanding of Upcaster.
The main problem is setting up the configuration. Indeed there are good instructions for initial set up for Axon. However, I am getting lost in more advanced configurations like Upcasting, more precisely where to write the EventProcessor and EventReply configurations.
My main goal is the same as mentioned above - to transform the Aggregate into another form by adding new properties. It would be great if there was some step-by-step guide for setting up the configurations for replaying and upcasting the Aggregate in event store.
My Axon Framework version is 3.4 and I am using PostgreSQL as an event store.

Daler Kamolov


adding new parts is much easier than changing existing ones.
I’d rather add new aggregates and events that represent the new features, instead of making existing aggregates bigger.
„Composition over inheritance“ and „open for extension, closed for modification“ come into my mind.

Upcasters are rather low-level (before deserialization takes place), hard to get right, and introduce coupling between the message api and technical aspects like serialization and axon configuration.

That said, i played around with an upcaster (NicknameChangedEventV1Upcaster)in my showcase-quarkus-eventsourcing.
The showcase builds upon microprofile, though.


Following https://docs.axoniq.io/reference-guide/operations-guide/production-considerations/versioning-events#writing-an-upcaster
We keep the main configuration inside AxonFrameworkConfiguration.kt and keep the Upcaster class near the rest of our Event classes so it’s easy to maintain future upcasts.
As mentioned by Johnny T at the moment we try to limit breaking changes as much as possible by creating new events and/or versioning the application itself.

Thanks Johnny, Michael, we will look at „Composition over inheritance“ and „open for extension, closed for modification“ way of solving this issue.

Thanks to all again!