{"record":{"id":"9454d0b2f0cf06ec","repo":"elsa-workflows/elsa-core","slug":"unknown-serialization-type-alias-typealias-only-registered","errorCode":null,"errorMessage":"Unknown serialization type alias '{typeAlias}'. Only registered aliases and supported compound aliases can be deserialized.","messagePattern":"Unknown serialization type alias '(.+?)'\\. Only registered aliases and supported compound aliases can be deserialized\\.","errorType":"validation","errorClass":"JsonException","httpStatus":null,"severity":"error","filePath":"src/modules/Elsa.Common/Serialization/SerializationTypeResolver.cs","lineNumber":65,"sourceCode":"    {\n        [typeof(IEnumerable)] = typeof(List<object>),\n        [typeof(ICollection)] = typeof(List<object>),\n        [typeof(IList)] = typeof(List<object>),\n        [typeof(IDictionary)] = typeof(Dictionary<string, object>)\n    };\n\n    /// <summary>\n    /// Resolves the specified serialization type alias.\n    /// </summary>\n    public static Type ResolveType(ISerializationTypeRegistry serializationTypeRegistry, string? typeAlias)\n    {\n        if (string.IsNullOrWhiteSpace(typeAlias))\n            throw new JsonException(\"The serialization type alias is missing.\");\n\n        if (TryResolveType(serializationTypeRegistry, typeAlias, out var type))\n            return type;\n\n        throw new JsonException(\n            $\"Unknown serialization type alias '{typeAlias}'. Only registered aliases and supported compound aliases can be deserialized.\");\n    }\n\n    /// <summary>\n    /// Attempts to resolve the specified serialization type alias.\n    /// </summary>\n    public static bool TryResolveType(ISerializationTypeRegistry serializationTypeRegistry, string typeAlias, out Type type)\n    {\n        IReadOnlyList<Type>? registeredTypes = null;\n        return TryResolveType(serializationTypeRegistry, typeAlias, ref registeredTypes, out type);\n    }\n\n    private static bool TryResolveType(ISerializationTypeRegistry serializationTypeRegistry, string typeAlias, ref IReadOnlyList<Type>? registeredTypes, out Type type)\n    {\n        if (serializationTypeRegistry.TryGetType(typeAlias, out var registeredType))\n        {\n            type = registeredType;\n            return true;","sourceCodeStart":47,"sourceCodeEnd":83,"githubUrl":"https://github.com/elsa-workflows/elsa-core/blob/fe9217bdfa0e27f0e09e45006eb6898f616e513d/src/modules/Elsa.Common/Serialization/SerializationTypeResolver.cs#L47-L83","documentation":"ResolveType maps a serialized type alias back to a CLR Type during JSON deserialization. When the alias is not registered in the ISerializationTypeRegistry and does not match a supported compound alias, Elsa cannot safely materialize the type and throws a JsonException so the deserialization fails loudly instead of loading an unknown type.","triggerScenarios":"Deserializing JSON whose $type / type alias field contains an alias that was never registered, or whose serialization producer registered types that the consuming application did not (e.g. missing module registration, trimmed/published app missing a type, or payload from a different Elsa version).","commonSituations":"Sharing workflow instance/checkpoint JSON between apps with different registered activities; renaming or removing an activity type; R2R/trimming stripping types; deserializing a payload produced by a newer Elsa version that registered extra aliases.","solutions":["Register the missing type alias via the serialization type registry before deserializing (ISerializationTypeRegistry / AddType<...>(\"alias\"))","Ensure the module/package defining the type is referenced and installed in the consuming app","Verify the JSON payload's type alias matches the alias used at serialization time (check for version skew)","If using trimming/PublishSingleFile, add the type to the TrimmerRootAssembly or disable trimming for the assembly"],"exampleFix":"// before: deserializing payload with alias \"my-custom-activity\" that is unregistered\nvar model = JsonSerializer.Deserialize<WorkflowEnvelope>(json);\n// after: register the alias first\nservices.AddSerialization(options => options.AddType<MyCustomActivity>(\"my-custom-activity\"));\nvar model = JsonSerializer.Deserialize<WorkflowEnvelope>(json);","handlingStrategy":"try-catch","validationCode":"var alias = ExtractAlias(json);\nvar known = alias is null || serializationTypeRegistry.TryGetType(alias, out _);\nif (!known) throw new InvalidOperationException($\"Alias '{alias}' is not registered before deserialize.\");","typeGuard":"bool IsRegisteredAlias(string alias) => !string.IsNullOrWhiteSpace(alias) && serializationTypeRegistry.TryGetType(alias, out _);","tryCatchPattern":"try { return JsonSerializer.Deserialize<T>(json); }\ncatch (JsonException ex) when (ex.Message.Contains(\"Unknown serialization type alias\"))\n{ logger.LogWarning(ex, \"Unregistered type alias in payload\"); return null; }","preventionTips":["Register every serializable type's alias in both producing and consuming apps","Pin Elsa package versions across services exchanging serialized workflows","Test round-trip serialization in CI","Avoid stripping assemblies with trimming without trimmer roots"],"tags":["json","deserialization","type-resolution"],"backgroundTag":"class-not-found","analyzedSha":"fe9217bdfa0e27f0e09e45006eb6898f616e513d","analyzedAt":"2026-09-13T20:32:34.702Z","contentChangedAt":"2026-09-13T20:32:34.702Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}