|
| 1 | +--- |
| 2 | +uid: akkadotnet-v14-upgrade-advisories |
| 3 | +title: Akka.NET v1.4 Upgrade Advisories |
| 4 | +--- |
| 5 | + |
| 6 | +# Akka.NET v1.4 Upgrade Advisories |
| 7 | +This document contains specific upgrade suggestions, warnings, and notices that you will want to pay attention to when upgrading between versions within the Akka.NET v1.4 roadmap. |
| 8 | + |
| 9 | +## Upgrading to Akka.NET v1.4.20 from Older Versions |
| 10 | + |
| 11 | +> [!NOTE] |
| 12 | +> This is an edge-case issue that only affects users who are sending primitive data types (i.e. `int`, `long`, `string`) directly over Akka.Remote or Akka.Persistence. |
| 13 | +
|
| 14 | +Between Akka.NET v1.4.19 and [v1.4.20](https://github.com/akkadotnet/akka.net/releases/tag/1.4.20) we introduced a regression in the wire format of the "primitive" serializer in Akka.NET v1.4.20 - the serializer responsible for transmitting `int`, `long`, and `string` as stand-alone messages in Akka.Remote and Akka.Persistence. |
| 15 | + |
| 16 | +The error message would look like this in clusters that are running a combination of v1.4.20 and any previous versions of Akka.NET: |
| 17 | + |
| 18 | +> `Serializer not defined for message with serializer id [6] and manifest []. Transient association error (association remains live). Cannot find manifest class [S] for serializer with id [17].` |
| 19 | +
|
| 20 | +You can see the PR that introduced this regression here: https://github.com/akkadotnet/akka.net/issues/4986 |
| 21 | + |
| 22 | +This change was originally introduced to assist with cross-platform wire compatibility between .NET Framework and .NET Core, because Microsoft changed the names of all primitive types between the two runtimes when .NET Core was originally introduced. |
| 23 | + |
| 24 | +**Workarounds**: |
| 25 | + |
| 26 | +To work around this issue, if you're affected by it (most users are not:) |
| 27 | + |
| 28 | +* Upgrade all of the nodes to v1.4.20 or later at once; |
| 29 | +* Or upgrade directly to Akka.NET v1.4.26 or later, which resolves this issue and prevents the regression from occurring. |
| 30 | + |
| 31 | +## Upgrading to Akka.NET v1.4.26 from Older Versions |
| 32 | + |
| 33 | +> [!NOTE] |
| 34 | +> This is an edge-case issue that only affects users who are sending primitive data types (i.e. `int`, `long`, `string`) directly over Akka.Remote or Akka.Persistence. |
| 35 | +
|
| 36 | +In Akka.NET v1.4.26 we have introduced a new setting: |
| 37 | + |
| 38 | +``` |
| 39 | +akka.actor.serialization-settings.primitive.use-legacy-behavior = on |
| 40 | +``` |
| 41 | + |
| 42 | +This setting is set of `on` by default and it resolves the backwards compatibility issue introduced in the "primitives" serializer described in our [v1.4.20 upgrade advisory](#upgrading-to-akkanet-v1420-from-older-versions). |
| 43 | + |
| 44 | +> [!IMPORTANT] |
| 45 | +> If you have: |
| 46 | +> * Previously upgraded to Akka.NET v1.4.20+ and you have not run into any issues; |
| 47 | +> * You have not yet upgraded to Akka.NET v1.4.20+; and |
| 48 | +> * You _do not_ plan on running both .NET Framework and .NET Core in the same cluster |
| 49 | +> Then you can safely upgrade to v1.4.26 using your normal deployment process. |
| 50 | +
|
| 51 | +If you are running a mixed .NET Core and .NET Framework cluster, see the process below. |
| 52 | + |
| 53 | +### Deploying v1.4.26 into Mixed .NET Core and .NET Framework Environments |
| 54 | +*However*, if you are attempting to run a mixed-mode cluster - i.e. some services running on .NET Framework and some running on .NET Core, you will eventually want to turn this setting to `off` in order to faciliate smooth operation between both platforms. |
| 55 | + |
| 56 | +#### Already Deployed v1.4.20 or Later |
| 57 | +If you've already deployed v1.4.20 and you have not had any issues with the primitives serializer, do the following: |
| 58 | + |
| 59 | +1. Before you upgrade to v1.4.26 or later set `akka.actor.serialization-settings.primitive.use-legacy-behavior = off` - so any future serialization of primitives will be handled correctly in a cross-platform way; |
| 60 | +2. Run your normal deployment process. |
| 61 | + |
| 62 | +#### Have Not Deployed v1.4.20 or Later |
| 63 | +If you have not previously deployed to v1.4.20 or later, then do the following: |
| 64 | + |
| 65 | +1. Deploy once with `akka.actor.serialization-settings.primitive.use-legacy-behavior = on` (the default); |
| 66 | +2. Once all nodes are completely upgraded to v1.4.26 and later, prepare a second deployment with `akka.actor.serialization-settings.primitive.use-legacy-behavior = off`; |
| 67 | +3. Complete the second deployment - you will be fine with all rolling upgrades moving forward. |
0 commit comments