What causes "Unhandled annotatable type '{annotatableType}'." in dotnet/efcore?

Update the database provider / EF Core packages so the generator knows about the annotatable type.

dotnet/efcore · error · ArgumentException

Unhandled annotatable type '{annotatableType}'.

Error message

Unhandled annotatable type '{annotatableType}'.

What it means

Thrown by IAnnotationCodeGenerator.RemoveAnnotationsHandledByConventions when the annotatable passed in is not one of the supported concrete types (model, entity type, complex type, fragment, property, complex property, key, foreign key, navigation, skip navigation, index, check constraint, trigger, overrides, sequence). It is a defensive ArgumentException indicating the code generator has no handler for that annotatable kind.

Source

Thrown at src/EFCore.Relational/Design/IAnnotationCodeGenerator.cs:258

            case IIndex index:
                RemoveAnnotationsHandledByConventions(index, annotations);
                return;

            case ITrigger trigger:
                RemoveAnnotationsHandledByConventions(trigger, annotations);
                return;

            case IRelationalPropertyOverrides overrides:
                RemoveAnnotationsHandledByConventions(overrides, annotations);
                return;

            case ISequence sequence:
                RemoveAnnotationsHandledByConventions(sequence, annotations);
                return;

            default:
                throw new ArgumentException(RelationalStrings.UnhandledAnnotatableType(annotatable.GetType()));
        }
    }

    /// <summary>
    ///     For the given annotations which have corresponding fluent API calls, returns those fluent API calls
    ///     and removes the annotations.
    /// </summary>
    /// <param name="model">The model to which the annotations are applied.</param>
    /// <param name="annotations">The set of annotations from which to generate fluent API calls.</param>
    IReadOnlyList<MethodCallCodeFragment> GenerateFluentApiCalls(
        IModel model,
        IDictionary<string, IAnnotation> annotations)
        => [];

    /// <summary>
    ///     For the given annotations which have corresponding fluent API calls, returns those fluent API calls
    ///     and removes the annotations.
    /// </summary>

View on GitHub (pinned to dbf9771522)

Solutions

Update the database provider / EF Core packages so the generator knows about the annotatable type.
If authoring a provider, override IAnnotationCodeGenerator and add a case for the new annotatable type.
Filter annotatables to only the supported set before passing them to the generator.
Report a bug to the provider if a built-in annotatable triggers this.

Example fix

// design-time, before
foreach (var a in allAnnotatables)
    generator.RemoveAnnotationsHandledByConventions(a, ann); // throws for unknown kind

// after (filter to supported kinds)
foreach (var a in allAnnotatables.Where(IsSupportedAnnotatable))
    generator.RemoveAnnotationsHandledByConventions(a, ann);

Defensive patterns

Strategy: type-guard

Validate before calling

static readonly HashSet<Type> Supported = new()
{
    typeof(IModel), typeof(IEntityType), typeof(IComplexType),
    typeof(IEntityTypeMappingFragment), typeof(IProperty), typeof(IComplexProperty),
    typeof(IRelationalPropertyOverrides), typeof(IKey), typeof(IForeignKey),
    typeof(INavigation), typeof(ISkipNavigation), typeof(IIndex),
    typeof(ICheckConstraint), typeof(ITrigger), typeof(ISequence)
};
if (!Supported.Contains(annotatable.GetType()))
    throw new NotSupportedException($"Unsupported annotatable {annotatable.GetType()}");
generator.RemoveAnnotationsHandledByConventions(annotatable, annotations);

Type guard

static bool IsHandledAnnotatable(IAnnotatable a)
    => a is IModel or IEntityType or IComplexType or IEntityTypeMappingFragment
        or IProperty or IComplexProperty or IRelationalPropertyOverrides or IKey
        or IForeignKey or INavigation or ISkipNavigation or IIndex
        or ICheckConstraint or ITrigger or ISequence;

Prevention

Filter annotatables to the supported set before invoking the generator.
Keep provider and EF Core versions aligned so new annotatable kinds are handled.
In custom providers, extend IAnnotationCodeGenerator for new annotatable types.

When it happens

Trigger: Reached at IAnnotationCodeGenerator.cs:258 (default case) during design-time annotation processing — typically scaffolding/reverse-engineering or migrations design-time code generation — when a custom or newly introduced IAnnotatable implementation is passed in.

Common situations: Custom providers/plugins introducing a new annotatable type without extending the code generator; EF Core version upgrade adding a new annotatable that the provider's generator hasn't been updated to handle; calling the internal annotation-removal API directly from tooling.

Related errors

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