dotnet/efcore · error · InvalidOperationException

Invalid token type: '{tokenType}'.

Error message

Invalid token type: '{tokenType}'.

What it means

Thrown by ExtractDocuments when, after locating the 'Documents' property in the Cosmos query response JSON, the token immediately following is not a StartArray. The shaper expects the Documents value to be a JSON array; any other token type (object, string, null) indicates a malformed or unexpected response payload and aborts document extraction.

Source

Thrown at src/EFCore.Cosmos/Query/Internal/CosmosShapedQueryCompilingExpressionVisitor.ShaperProcessingExpressionVisitor.ClientMethods.cs:36

        private static readonly byte EndArrayByte = Encoding.UTF8.GetBytes("]")[0];
        private static readonly byte NextItemByte = Encoding.UTF8.GetBytes(",")[0];

        public static ReadOnlyMemory<byte> ExtractDocuments(ReadOnlyMemory<byte> data)
        {
            var documentsReader = new Utf8JsonReader(data.Span);

            documentsReader.Read();
            Debug.Assert(documentsReader.TokenType == JsonTokenType.StartObject);

            documentsReader.Read();
            while (documentsReader.TokenType == JsonTokenType.PropertyName)
            {
                if (documentsReader.ValueTextEquals("Documents"))
                {
                    documentsReader.Read();
                    var token = documentsReader.TokenType;
                    return token != JsonTokenType.StartArray
                        ? throw new InvalidOperationException(CoreStrings.JsonReaderInvalidTokenType(token))
                        : data[(int)documentsReader.BytesConsumed..];
                }

                documentsReader.Skip();
                documentsReader.Read();
            }

            throw new InvalidOperationException(CoreStrings.JsonReaderInvalidTokenType(documentsReader.TokenType));
        }

        public static bool TryMaterializeNextJsonCollectionItem<T>(
            QueryContext queryContext,
            ReadOnlyMemory<byte> data,
            Shaper<T> shaper,
            int ordinal,
            out int bytesConsumed,
            [NotNullWhen(true)] out T? result)
        {

View on GitHub (pinned to dbf9771522)

Solutions

1. Ensure no middleware/proxy rewrites the Cosmos response JSON before EF reads it.
2. Update the EF Core Cosmos provider and Azure Cosmos SDK to matching, supported versions.
3. If using a gateway or emulator, verify it returns the standard { "Documents": [...] } shape.
4. Capture the raw response to confirm the Documents token type and report a bug if non-standard.

try
{
    return await query.ToListAsync();
}
catch (InvalidOperationException ex) when (ex.Message.Contains("Invalid token type"))
{
    logger.LogError(ex, "Malformed Cosmos response payload");
    throw;
}

When it happens

Trigger: The Cosmos response payload's 'Documents' node is not an array (e.g. an object or scalar), which can happen with non-standard server responses, gateway proxy rewriting, or a malformed response. This is a shaper-level deserialization guard.

Common situations: Custom response interceptors/proxies that reshape the payload. Emulator or gateway bugs returning unexpected JSON. Version mismatch between EF Core Cosmos and the Cosmos SDK response contract.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• Invalid token type: '{tokenType}'.
• The LINQ expression '{expression}' could not be translated.
• Unhandled expression node type '{nodeType}'.
• The type '{givenType}' cannot be mapped as a dictionary beca
• The value '{value}' provided for argument '{argumentName}' m

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