dotnet/efcore · error · InvalidOperationException

The entity type '{entityType}' is mapped to the 'DbFunction'

Error message

The entity type '{entityType}' is mapped to the 'DbFunction' named '{functionName}' with return type '{returnType}'. Ensure that the mapped function returns 'IQueryable<{clrType}>'.

What it means

Thrown when a mapped DbFunction's return type does not match the entity type. The function must return IQueryable<TEntityClrType> exactly; the validator rejects scalar DbFunctions or any IQueryable<T> whose element type differs from the entity's ClrType. The first generic argument of the return type must equal entityType.ClrType.

Source

Thrown at src/EFCore.Relational/Infrastructure/RelationalModelValidator.cs:447

        var mappedFunction = entityType.Model.FindDbFunction(mappedFunctionName);
        if (mappedFunction == null)
        {
            throw new InvalidOperationException(
                RelationalStrings.MappedFunctionNotFound(entityType.DisplayName(), mappedFunctionName));
        }

        if (entityType.BaseType != null)
        {
            throw new InvalidOperationException(
                RelationalStrings.InvalidMappedFunctionDerivedType(
                    entityType.DisplayName(), mappedFunctionName, entityType.BaseType.DisplayName()));
        }

        if (mappedFunction.IsScalar
            || mappedFunction.ReturnType.GetGenericArguments()[0] != entityType.ClrType)
        {
            throw new InvalidOperationException(
                RelationalStrings.InvalidMappedFunctionUnmatchedReturn(
                    entityType.DisplayName(),
                    mappedFunctionName,
                    mappedFunction.ReturnType.ShortDisplayName(),
                    entityType.ClrType.ShortDisplayName()));
        }

        if (mappedFunction.Parameters.Count > 0)
        {
            var parameters = "{"
                + string.Join(
                    ", ",
                    mappedFunction.Parameters.Select(p => "'" + p.Name + "'"))
                + "}";
            throw new InvalidOperationException(
                RelationalStrings.InvalidMappedFunctionWithParameters(
                    entityType.DisplayName(), mappedFunctionName, parameters));
        }

View on GitHub (pinned to dbf9771522)

Solutions

Change the DbFunction method to return IQueryable<{YourEntity}>.
Ensure the element type exactly equals the entity's ClrType (no base/derived substitution).
Register a separate parameterless scalar DbFunction if you actually want a scalar value, and remove the entity ToFunction mapping.

Example fix

// before
public IQueryable<Post> GetBlogs() => ...;
modelBuilder.Entity<Blog>().ToFunction("GetBlogs");

// after
public IQueryable<Blog> GetBlogs() => FromSqlInterpolated(...);
modelBuilder.Entity<Blog>().ToFunction("GetBlogs");

Defensive patterns

Strategy: validation

Validate before calling

foreach (var et in modelBuilder.Model.GetEntityTypes())
{
    var fn = et.GetFunctionName();
    if (fn == null) continue;
    var dbFn = et.Model.FindDbFunction(fn);
    if (dbFn.IsScalar || dbFn.ReturnType.GetGenericArguments().FirstOrDefault() != et.ClrType)
        throw new InvalidOperationException($"DbFunction {fn} return type must be IQueryable<{et.ClrType.Name}>");
}

Type guard

// Guard a method returns the right IQueryable element type
static bool ReturnsEntityQueryable<T>(MethodInfo m) =>
    m.ReturnType == typeof(IQueryable<T>);

Try / catch

try { _ = ctx.Model; } catch (InvalidOperationException ex) when (ex.Message.Contains("returns")) { /* align DbFunction return type with entity ClrType */ }

Prevention

Declare DbFunction methods as public IQueryable<TEntity> on the DbContext.
Keep a test that checks each entity-mapped DbFunction returns IQueryable of the entity type.

When it happens

Trigger: Pointing HasDbFunction at a method returning IQueryable<OtherType>; a scalar DbFunction; a method returning a single entity instead of IQueryable<T>; ToFunction on an entity whose DbFunction returns a different type.

Common situations: Reusing an existing DbFunction for a different entity; refactoring the DbFunction method signature; copy-paste between entities leaving a stale return type.

Related errors

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