dotnet/efcore · error · NotImplementedException

ArrayCreation: multi-dimensional array: {arrayCreation}

Error message

ArrayCreation: multi-dimensional array: {arrayCreation}

What it means

`VisitArrayCreationExpression` throws `NotImplementedException` when `arrayTypeSymbol.Rank > 1` — multi-dimensional arrays (`int[,]`, `string[,,]`) are not supported by this translator or by LINQ expression trees generally. Only single-dimensional arrays (`int[]`) translate.

Source

Thrown at src/EFCore.Design/Query/Internal/CSharpToLinqTranslator.cs:236

            ? throw new InvalidOperationException($"Argument with ref/out: {argument}")
            : Visit(argument.Expression, expectedType);

    /// <summary>
    ///     This is an internal API that supports the Entity Framework Core infrastructure and not subject to
    ///     the same compatibility standards as public APIs. It may be changed or removed without notice in
    ///     any release. You should only use it directly in your code with extreme caution and knowing that
    ///     doing so can result in application failures when updating to a new Entity Framework Core release.
    /// </summary>
    public override Expression VisitArrayCreationExpression(ArrayCreationExpressionSyntax arrayCreation)
    {
        if (_semanticModel.GetTypeInfo(arrayCreation).Type is not IArrayTypeSymbol arrayTypeSymbol)
        {
            throw new InvalidOperationException($"ArrayCreation: non-array type symbol: {arrayCreation}");
        }

        if (arrayTypeSymbol.Rank > 1)
        {
            throw new NotImplementedException($"ArrayCreation: multi-dimensional array: {arrayCreation}");
        }

        var elementType = ResolveType(arrayTypeSymbol.ElementType);
        Check.DebugAssert(elementType is not null);

        return arrayCreation.Initializer is null
            ? NewArrayBounds(elementType, Visit(arrayCreation.Type.RankSpecifiers[0].Sizes[0]))
            : NewArrayInit(elementType, arrayCreation.Initializer.Expressions.Select(e => Visit(e)));
    }

    /// <summary>
    ///     This is an internal API that supports the Entity Framework Core infrastructure and not subject to
    ///     the same compatibility standards as public APIs. It may be changed or removed without notice in
    ///     any release. You should only use it directly in your code with extreme caution and knowing that
    ///     doing so can result in application failures when updating to a new Entity Framework Core release.
    /// </summary>
    public override Expression VisitBinaryExpression(BinaryExpressionSyntax binary)
    {

View on GitHub (pinned to dbf9771522)

Solutions

Replace the multi-dimensional array with a jagged array (`int[][]`) or a flat `int[]` plus index math.
Hoist the data out of the query and pass it in as a captured, single-dimensional structure.

Example fix

// before
var grid = new int[2, 3];
var q = ctx.X.Where(x => lookup(grid, x));
// after
var grid = new int[2][];   // jagged
var q = ctx.X.Where(x => lookup(grid, x));

Defensive patterns

Strategy: validation

Validate before calling

// Reject multi-dimensional arrays up front.
var arrayType = semanticModel.GetTypeInfo(arrayCreationNode).Type as IArrayTypeSymbol;
if (arrayType is { Rank: > 1 })
    throw new NotSupportedException("Multi-dimensional arrays are not supported in precompiled queries; use a jagged array.");

translator.Translate(arrayCreationNode, semanticModel);

Try / catch

try { translator.Translate(node, semanticModel); }
catch (NotImplementedException ex) when (ex.Message.Contains("multi-dimensional array"))
{ /* convert to jagged array and rebuild */ }

Prevention

Use single-dimensional or jagged arrays (`T[][]`) instead of `T[,]` in queries.
Avoid passing matrix/grid data structures into precompiled query expressions.

When it happens

Trigger: A precompiled query containing a rectangular/multi-dimensional array literal, e.g. `new int[2, 3] { ... }` or passing a `T[,]` constant into the query.

Common situations: Migrating numerical/matrix code or interop helpers that use `[,]` arrays into a query that gets precompiled.

Related errors

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