dotnet/efcore · error · InvalidOperationException

JsonElementMappingNotFound

JsonElementMappingNotFound

Error message

No JSON element mapping was found for '{structuralType}.{name}' on column '{columnName}'.

What it means

Thrown by JsonQueryExpression.GetJsonElement (JsonQueryExpression.cs:313) when FindJsonElement returns null: no JSON element mapping for the given property/navigation/complex property exists on the column this expression references. EF resolves JSON paths via IRelationalJsonElement mappings matched to a specific column; if none matches (property has no JSON representation on that column), the path cannot be built and EF throws.

Source

Thrown at src/EFCore.Relational/Query/JsonQueryExpression.cs:313

    /// <summary>
    ///     Finds the <see cref="IRelationalJsonElement" /> for the given property/navigation/complex property within the
    ///     JSON column referenced by this expression by matching <see cref="JsonColumn" />'s underlying
    ///     <see cref="ColumnExpression.Column" /> against <see cref="IRelationalJsonElement.ContainingColumn" />. This
    ///     disambiguates entity-splitting, TPT and TPC scenarios where the same property has multiple JSON element
    ///     mappings — one per concrete table.
    ///     <see cref="IRelationalJsonElement.PropertyName" /> may be <see langword="null" /> for shadow keys that have
    ///     no JSON representation; callers iterating over <see cref="ITypeBase.GetProperties" /> must handle that case
    ///     and skip them.
    /// </summary>
    /// <param name="propertyBase">The property, navigation or complex property to look up.</param>
    /// <returns>The JSON element mapping for <paramref name="propertyBase" />.</returns>
    public virtual IRelationalJsonElement GetJsonElement(IPropertyBase propertyBase)
    {
        var column = JsonColumn.Column
            ?? throw new InvalidOperationException(
                RelationalStrings.JsonQueryExpressionWithoutUnderlyingColumn(StructuralType.DisplayName()));
        return FindJsonElement(propertyBase)
            ?? throw new InvalidOperationException(
                RelationalStrings.JsonElementMappingNotFound(propertyBase.DeclaringType.DisplayName(), propertyBase.Name, column.Name));
    }

    /// <summary>
    ///     Finds the <see cref="IRelationalJsonElement" /> for the given property/navigation/complex property within the
    ///     JSON column referenced by this expression by matching <see cref="JsonColumn" />'s underlying
    ///     <see cref="ColumnExpression.Column" /> against <see cref="IRelationalJsonElement.ContainingColumn" />, or returns
    ///     <see langword="null" /> if no such element exists (including when <see cref="JsonColumn" /> has no underlying
    ///     <see cref="ColumnExpression.Column" />, e.g. for synthetic JSON expansions over OPENJSON / json_each, or for
    ///     iterated properties such as shadow keys that have no JSON representation).
    /// </summary>
    /// <param name="propertyBase">The property, navigation or complex property to look up.</param>
    /// <returns>The JSON element mapping for <paramref name="propertyBase" />, or <see langword="null" /> if not found.</returns>
    public virtual IRelationalJsonElement? FindJsonElement(IPropertyBase propertyBase)
    {
        var containingColumn = JsonColumn.Column;
        if (containingColumn is null)
        {

View on GitHub (pinned to dbf9771522)

Solutions

Ensure the property has a JSON element mapping on the column referenced by this JsonQueryExpression (check GetJsonElementMappings and ContainingColumn).
In TPT/TPC/splitting, make sure the query's JSON expression targets the concrete table whose column holds that property.
Skip properties with no JSON representation (shadow keys) using FindJsonElement before GetJsonElement.
Regenerate migrations / verify the model so every expected property has a mapping on the relevant column.

Example fix

// before - GetJsonElement throws when no mapping exists for the property on this column
var element = jsonExpr.GetJsonElement(someProperty); // JsonElementMappingNotFound

// after - probe first and handle the unmapped case
var element = jsonExpr.FindJsonElement(someProperty);
if (element is null) {
    // property has no JSON representation on this column; skip or handle (e.g. shadow key)
    continue;
}

Defensive patterns

Strategy: validation

Validate before calling

// Probe with FindJsonElement and handle missing mappings gracefully.
var element = jsonExpr.FindJsonElement(prop);
if (element is null) {
    // property has no JSON mapping on this column; skip or handle
    continue;
}
// use element.PropertyName ...

Type guard

bool HasJsonMappingOnColumn(IPropertyBase p, ColumnExpression c)
    => p.GetJsonElementMappings().Any(m => ReferenceEquals(m.Element.ContainingColumn, c));

Prevention

Use FindJsonElement before GetJsonElement to avoid throwing on unmapped properties.
In TPT/TPC/splitting, ensure the JSON expression targets the concrete table holding the property.
Skip shadow keys (no JSON representation) when iterating properties.
Keep migrations and JSON column mappings consistent across the model.

When it happens

Trigger: Calling GetJsonElement for a property/navigation/complex property that has no JSON element mapping on the JsonQueryExpression's column. Happens in TPT/TPC/entity-splitting where a property has multiple JSON mappings but none on this column, or when querying a property that isn't part of the JSON document (e.g. a shadow key or a property mapped elsewhere).

Common situations: TPT/TPC with JSON-mapped owned types where the property maps to a different concrete table's column; querying a property that was removed from the JSON mapping; provider/model inconsistency after a migration; shadow keys that have no JSON representation being resolved.

Related errors

AI-assisted analysis of dotnet/efcore@dbf9771522 (2026-08-06). Data as JSON: /api/errors/0f8b8a89a14794fb. Report an issue: GitHub.