dotnet/efcore · error · InvalidOperationException

Unable to generate a valid 'id' value to execute a 'ReadItem

Error message

Unable to generate a valid 'id' value to execute a 'ReadItem' query. This usually happens when the value provided for one of the properties is 'null' or an empty string. Provide a value that's not 'null' or an empty string.

What it means

Thrown by TryGetResourceId when the generated Cosmos resource 'id' string is null or empty. The id is composed from the entity's jsonIdDefinition properties; if one of those property values is null or an empty string, the composed id is invalid and the ReadItem query cannot be executed.

Source

Thrown at src/EFCore.Cosmos/Query/Internal/CosmosShapedQueryCompilingExpressionVisitor.ReadItemQueryingEnumerable.cs:94

            Check.DebugAssert(
                jsonIdDefinition != null,
                "Should not be using this enumerable if not using ReadItem, which needs an id definition.");

            var values = new List<object>(jsonIdDefinition.Properties.Count);
            foreach (var property in jsonIdDefinition.Properties)
            {
                var value = _readItemInfo.PropertyValues[property] switch
                {
                    SqlParameterExpression { Name: var parameterName } => _cosmosQueryContext.Parameters[parameterName],
                    SqlConstantExpression { Value: var constantValue } => constantValue,
                    _ => throw new UnreachableException()
                };

                values.Add(value);
            }

            resourceId = jsonIdDefinition.GenerateIdString(values);
            return string.IsNullOrEmpty(resourceId) ? throw new InvalidOperationException(CosmosStrings.InvalidResourceId) : true;
        }

        private sealed class AsyncEnumerator : IAsyncEnumerator<T>
        {
            private readonly CosmosQueryContext _cosmosQueryContext;
            private readonly string _cosmosContainer;
            private readonly PartitionKey _cosmosPartitionKey;
            private readonly Shaper<T> _shaper;
            private readonly Type _contextType;
            private readonly IDiagnosticsLogger<DbLoggerCategory.Query> _queryLogger;
            private readonly bool _standAloneStateManager;
            private readonly IConcurrencyDetector _concurrencyDetector;
            private readonly IExceptionDetector _exceptionDetector;
            private readonly ReadItemQueryingEnumerable<T> _readItemEnumerable;
            private readonly CancellationToken _cancellationToken;

            private ReadOnlyMemory<byte>? _response;
            private bool _hasExecuted;

View on GitHub (pinned to dbf9771522)

Solutions

Ensure all properties contributing to the id definition are non-null and non-empty before executing the query.
Validate key values at the application boundary and reject null/empty early.
Review the entity's id composition (HasId/partition key mapping) to ensure only required, always-set properties are included.
Provide explicit parameter values rather than relying on defaults that may be null.

Example fix

// before
var id = Guid.NewGuid().ToString();
var region = string.Empty;
var blog = await context.Blogs.WithPartitionKey(region).Where(b => b.Id == id).FirstAsync();
// after
var id = Guid.NewGuid().ToString();
var region = "us-east"; // ensure non-empty
var blog = await context.Blogs.WithPartitionKey(region).Where(b => b.Id == id).FirstAsync();

Defensive patterns

Strategy: validation

Validate before calling

// Validate all id-defining property values before querying
foreach (var idProp in entity.GetJsonIdDefinition().Properties)
{
    var v = GetValue(idProp);
    if (v is null or "") throw new ArgumentException($"{idProp} must be non-null/non-empty for a ReadItem query");
}

Prevention

Validate key/id properties at the application boundary before querying.
Ensure id-defining properties are non-nullable and always set.
Add a guard in repository code that constructs ReadItem-style queries.

When it happens

Trigger: A ReadItem-optimized query where one of the properties contributing to the document id is null or string.Empty at execution time. This happens when the id is composed of multiple PK parts and one part is missing.

Common situations: Entities whose id is built from a composite of properties where a non-Id segment (e.g. a discriminator or region prefix) is null. Data where a key property was not set before querying. Configuring a JsonIdDefinition that includes a nullable property.

Related errors

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