System.Text.Json: 'Deserialization of interface or abstract types is not supported'

System.NotSupportedException: Deserialization of interface or abstract types is not supported. Type 'IShape'. Path: $ | LineNumber: 0 | BytePositionInLine: 1. means you asked System.Text.Json to create an object of a type that cannot be created: an interface or an abstract class. The JSON does not say which concrete class to build, so the serializer stops at the first character.

Deserialize the concrete class if you know it. If the JSON can hold several kinds of object, mark the base class with [JsonPolymorphic] and one [JsonDerivedType] per subclass, and let a $type property in the JSON pick the class.

The error

Unhandled exception. System.NotSupportedException: Deserialization of interface or abstract types is not supported. Type 'IShape'. Path: $ | LineNumber: 0 | BytePositionInLine: 1.
 ---> System.NotSupportedException: Deserialization of interface or abstract types is not supported. Type 'IShape'.

The call was JsonSerializer.Deserialize<IShape>(json) on {"Radius":2}. Deserialize<Shape>, where Shape is an abstract class implementing IShape, gave the same message with Type 'Shape'.

Why it happens

To deserialize, the serializer must call a constructor and then set properties. An interface has no constructor, and an abstract class cannot be instantiated, so there is nothing to call. The JSON {"Radius":2} looks like a circle to a person, but nothing in it tells the serializer that Circle is meant, and System.Text.Json never guesses a subclass from the property names.

The same exception surfaces outside your own calls. A minimal API endpoint declared as (IShape shape) => ... threw it while binding the request body, and the client got a 500, not the 400 a malformed body gets, because this is a NotSupportedException about your type rather than a JsonException about the request.

The fix

If you know the concrete type, use it: Deserialize<Circle> on the same JSON printed Circle, area 12.57. If the JSON mixes kinds, describe the hierarchy on the base class:

[JsonPolymorphic(TypeDiscriminatorPropertyName = "$type")]
[JsonDerivedType(typeof(Circle), "circle")]
[JsonDerivedType(typeof(Square), "square")]
public abstract class Shape
{
    public abstract double Area();
}

A round trip through an array of shapes, serialized and read back:

[{"$type":"circle","Radius":2},{"$type":"square","Side":3}]
Circle, area 12.57
Square, area 9.00

The serializer writes the $type value when it serializes through the base type and reads it to pick the class. $type is also the default name: a bare [JsonPolymorphic] on an interface with one [JsonDerivedType] wrote and read $type the same way, so the attributes work on IShape too. Two cases still failed, both with "The JSON payload for polymorphic interface or abstract type 'Fixed.Shape' must specify a type discriminator": JSON with no $type at all, and JSON with $type after the other properties. The second one worked once the options set AllowOutOfOrderMetadataProperties = true, which matters when the JSON comes from a system that does not put the discriminator first.

How it was reproduced

A console project (dotnet new console) and an empty web project for the endpoint, on .NET SDK 10.0.402 with runtime 10.0.13 and System.Text.Json from the shared framework, on Windows 11. IShape, Shape, Circle, Square and the Fixed namespace that held the attributed copies are the test's own.

Frequently asked

How do I deserialize an interface with System.Text.Json?

Either deserialize the concrete class that implements it, or put [JsonPolymorphic] and one [JsonDerivedType(typeof(Concrete), "name")] per implementation on the base type, so a $type property in the JSON says which class to create.

What is $type in System.Text.Json JSON?

It is the default type discriminator for polymorphic serialization. When a type carries [JsonDerivedType] attributes, the serializer writes $type with the name you registered and reads it back to choose the class.

Why does my polymorphic JSON say it must specify a type discriminator?

The JSON has no $type property, or $type is not the first property of the object. Add the discriminator, or set AllowOutOfOrderMetadataProperties = true on JsonSerializerOptions when it comes later in the object.

Another System.Text.Json error with a one-line cause is a possible object cycle was detected. More decoded errors in the Fixes category.