elsa-workflows/elsa-core · error · JsonException

The serialization type alias is missing.

Error message

The serialization type alias is missing.

What it means

SerializationTypeResolver.ResolveType resolves a serialization type alias through ISerializationTypeRegistry. An empty/whitespace/null alias throws this JsonException (a distinct message from the unknown-alias error that follows registry lookup).

Solutions

1. Ensure serialized payloads include the type-alias property with a non-empty registered alias.
2. Enable/restore Elsa's type-alias serialization settings so the discriminator is written.
3. Check the input JSON for a missing/empty "type"/alias field at the failing path.
4. If the alias is optional in your scenario, use TryResolveType which tolerates missing aliases instead.

Example fix

// before
{"activity": {"id": "a1"}}
// after
{"activity": {"type": "HttpEndpoint", "id": "a1"}}

if (string.IsNullOrWhiteSpace(typeAlias))
    throw new JsonException("Payload is missing the required type-alias discriminator.");

bool HasTypeAlias(JsonElement e, string prop = "type") => e.ValueKind == JsonValueKind.Object && e.TryGetProperty(prop, out var p) && p.ValueKind == JsonValueKind.String && !string.IsNullOrWhiteSpace(p.GetString());

try { type = SerializationTypeResolver.ResolveType(registry, alias); }
catch (JsonException ex) when (ex.Message.Contains("alias")) { logger.LogError(ex, "Bad or missing type alias in payload"); }

When it happens

Trigger: Deserializing payload where the type-discriminator property (e.g. $type/type alias field) is absent, null, or an empty string, and the resolver is invoked with that value.

Common situations: Hand-written or trimmed JSON missing the type field; serializers configured with an alias-writing setting disabled; migrations dropping the discriminator property; clients posting polymorphic payloads without the type metadata.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Unsupported console stream value
• The persisted external authentication value could not be…
• The upstream logout mode must be a string.
• The upstream logout mode is not supported.
• Expected StartObject token

AI-assisted analysis of elsa-workflows/elsa-core@fe9217bdfa (2026-09-13). Data as JSON: /api/errors/6edf7fa92cc24153. Report an issue: GitHub.

Appendix: source

Thrown at src/modules/Elsa.Common/Serialization/SerializationTypeResolver.cs:60

        [typeof(IDictionary<,>)] = typeof(Dictionary<,>),
        [typeof(IReadOnlyDictionary<,>)] = typeof(Dictionary<,>)
    };

    private static readonly IDictionary<Type, Type> CollectionInterfaceMappings = new Dictionary<Type, Type>
    {
        [typeof(IEnumerable)] = typeof(List<object>),
        [typeof(ICollection)] = typeof(List<object>),
        [typeof(IList)] = typeof(List<object>),
        [typeof(IDictionary)] = typeof(Dictionary<string, object>)
    };

    /// <summary>
    /// Resolves the specified serialization type alias.
    /// </summary>
    public static Type ResolveType(ISerializationTypeRegistry serializationTypeRegistry, string? typeAlias)
    {
        if (string.IsNullOrWhiteSpace(typeAlias))
            throw new JsonException("The serialization type alias is missing.");

        if (TryResolveType(serializationTypeRegistry, typeAlias, out var type))
            return type;

        throw new JsonException(
            $"Unknown serialization type alias '{typeAlias}'. Only registered aliases and supported compound aliases can be deserialized.");
    }

    /// <summary>
    /// Attempts to resolve the specified serialization type alias.
    /// </summary>
    public static bool TryResolveType(ISerializationTypeRegistry serializationTypeRegistry, string typeAlias, out Type type)
    {
        IReadOnlyList<Type>? registeredTypes = null;
        return TryResolveType(serializationTypeRegistry, typeAlias, ref registeredTypes, out type);
    }

    private static bool TryResolveType(ISerializationTypeRegistry serializationTypeRegistry, string typeAlias, ref IReadOnlyList<Type>? registeredTypes, out Type type)

View on GitHub (pinned to fe9217bdfa)