System.Text.Json.JsonException: A possible object cycle was detected. This can either be due to a cycle or if the object depth is larger than the maximum allowed depth of 64. Consider using ReferenceHandler.Preserve on JsonSerializerOptions to support cycles.
Obiectul întors are o referință circulară (de exemplu Categorie.Produse și Produs.Categorie, ca la entitățile EF Core), iar serializarea JSON intră în buclă până la adâncimea maximă 64. Întoarce un DTO fără referința înapoi sau setează ReferenceHandler.IgnoreCycles.
Explicat de Tudor Andrei Dumitrescu, Senior Software Developer, fondatorul Academiei ProgramatorilorActualizat la
Ce înseamnă
Când întorci un obiect dintr-un endpoint, ASP.NET Core îl serializează cu System.Text.Json, urmărind toate proprietățile. Dacă o categorie are lista de produse, iar fiecare produs are înapoi proprietatea Categorie, serializatorul scrie categoria, apoi produsul, apoi din nou categoria și tot așa. Implicit nu detectează ciclurile, așa că se oprește când adâncimea depășește 64 și aruncă excepția; răspunsul devine 500 (uneori după ce o parte din JSON a fost deja trimisă).
Cazul tipic sunt entitățile EF Core cu navigări în ambele sensuri, încărcate cu Include. Partea Path: $.Produse.Categorie.Produse... din mesaj arată exact bucla. Soluția recomandată este să nu expui entitățile direct, ci DTO-uri care conțin doar ce trebuie clientului. Opțiunea ReferenceHandler.IgnoreCycles scrie null în locul referinței repetate.
De ce apare: cauzele frecvente
1Entități cu navigări în ambele sensuri
app.MapGet("/categorii", (MagazinDb db) =>
db.Categorii.Include(c => c.Produse).ToList());app.MapGet("/categorii", (MagazinDb db) =>
db.Categorii.Select(c => new CategorieDto(c.Nume, c.Produse.Select(p => p.Nume).ToList())).ToList());DTO-ul nu are referința înapoi spre categorie, deci nu există ciclu.
2Fără DTO: ignoră ciclurile la serializare
var app = builder.Build();builder.Services.ConfigureHttpJsonOptions(o =>
o.SerializerOptions.ReferenceHandler = ReferenceHandler.IgnoreCycles);
var app = builder.Build();IgnoreCycles (din System.Text.Json.Serialization) scrie null acolo unde ar reapărea un obiect deja în curs de scriere.
Repară eroarea, direct în pagină
GET /categorii răspunde 500: A possible object cycle was detected..., pentru că fiecare produs are referință înapoi la categoria lui. Repară endpoint-ul ca să întoarcă un DTO: pentru fiecare categorie, numele și lista numelor produselor.
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
var it = new Categorie { Nume = "IT" };
it.Produse.Add(new Produs { Nume = "Mouse", Categorie = it });
it.Produse.Add(new Produs { Nume = "Laptop", Categorie = it });
var categorii = new List<Categorie> { it };
app.MapGet("/categorii", () => categorii);
app.Run();
public class Categorie
{
public string Nume { get; set; } = "";
public List<Produs> Produse { get; } = new();
}
public class Produs
{
public string Nume { get; set; } = "";
public Categorie? Categorie { get; set; }
}
public record CategorieDto(string Nume, List<string> Produse);GET /categorii → 200 OK
[{"nume":"IT","produse":["Mouse","Laptop"]}]Indiciu
Construiește cu Select obiecte noi care nu conțin referința de la produs la categorie.
Reparația
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
var it = new Categorie { Nume = "IT" };
it.Produse.Add(new Produs { Nume = "Mouse", Categorie = it });
it.Produse.Add(new Produs { Nume = "Laptop", Categorie = it });
var categorii = new List<Categorie> { it };
app.MapGet("/categorii", () =>
categorii.Select(c => new CategorieDto(c.Nume, c.Produse.Select(p => p.Nume).ToList())).ToList());
app.Run();
public class Categorie
{
public string Nume { get; set; } = "";
public List<Produs> Produse { get; } = new();
}
public class Produs
{
public string Nume { get; set; } = "";
public Categorie? Categorie { get; set; }
}
public record CategorieDto(string Nume, List<string> Produse);De ce merge
Serializatorul urma Categorie.Produse, apoi Produs.Categorie, apoi din nou Produse, până la adâncimea maximă. Proiecția în CategorieDto copiază doar numele categoriei și numele produselor, deci obiectul întors nu mai are nicio referință circulară. În plus, clientul primește exact datele de care are nevoie, nu modelul intern.
Alte forme ale mesajului
System.Text.Json.JsonException: A possible object cycle was detected. This can either be due to a cycle or if the object depth is larger than the maximum allowed depth of 64. Consider using ReferenceHandler.Preserve on JsonSerializerOptions to support cycles. Path: $.Produse.Categorie.Produse.Categorie.Produse.Categorie.Nume.
Cum o eviți pe viitor
- Nu întoarce entitățile EF Core direct din API: proiectează în DTO-uri cu
Select. - Dacă ai nevoie de navigarea înapoi doar în cod, marchează-o cu
[JsonIgnore]pe entitate. - Evită
ReferenceHandler.Preserveîn API-urile publice: adaugă$id/$refîn JSON, pe care puțini clienți îl înțeleg.
Întrebări frecvente
De ce nu am eroarea fără Include?
Fără Include, colecția Produse e goală (nu e încărcată), deci nu există ciclu în memorie. Ciclul apare când ambele capete sunt încărcate.
IgnoreCycles sau Preserve?
IgnoreCycles păstrează JSON-ul simplu și pune null la referința repetată. Preserve păstrează referințele cu $id și $ref, util doar dacă și clientul folosește System.Text.Json cu aceeași opțiune.
Erori înrudite
System.NotSupportedException: Serialization and deserialization of 'System.Type' instances is not supported. Path: $.Tip. Obiectul întors conține o proprietate de tip System.Type (de exemplu GetType() sau o excepție întreagă), pe care System.Text.Json refuză să o serializeze din motive de securitate. Întoarce doar textul de care ai nevoie: GetType().Name sau un DTO cu câmpuri simple. System.InvalidOperationException: The JSON property name for 'Produs.nume' collides with another property. Două proprietăți ale aceluiași tip ajung la același nume în JSON, de exemplu Nume (camelCase: nume) și Denumire marcată [JsonPropertyName("nume")]. Serializatorul nu poate scrie două chei identice, deci aruncă excepția (500). Dă-le nume JSON diferite sau ignoră una. System.InvalidOperationException: Each parameter in the deserialization constructor on type 'Produs' must bind to an object property or field on deserialization. Each parameter name must match with a property or field on the object. Fields are only considered when 'JsonSerializerOptions.IncludeFields' is enabled. The match can be case-insensitive. System.Text.Json creează obiectul prin constructor și potrivește fiecare parametru cu o proprietate după nume. Un parametru numit altfel decât proprietatea (numeProdus față de Nume) nu are pereche, deci tipul nu poate fi deserializat. Redenumește parametrul ca proprietatea. Învață ASP.NET Core de la zero, cu exerciții la fiecare lecție
Curs ASP.NET Core: lecții scurte, fiecare cu un exercițiu verificat automat, direct în browser. Primele 20 lecții sunt gratuite.
