...
Eroare C# · Fișiere, HTTP, URI și JSON

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.

Pe scurt

Obiectul pe care îl serializezi în JSON conține o buclă de referințe: un client are comenzi, iar fiecare comandă are înapoi clientul. Serializatorul ar scrie la nesfârșit. Ignoră legătura inversă cu `[JsonIgnore]`, folosește `ReferenceHandler.IgnoreCycles` sau serializează un obiect simplu (DTO) fără bucle.

Explicat de Tudor Andrei Dumitrescu, Senior Software Developer, fondatorul Academiei ProgramatorilorActualizat la

Ce înseamnă

JsonSerializer.Serialize parcurge toate proprietățile publice, recursiv. Dacă Client.Comenzi conține o Comanda, iar Comanda.Client arată înapoi spre același client, parcurgerea ar intra într-o buclă infinită: client, comenzi, client, comenzi... După 64 de niveluri, System.Text.Json se oprește și aruncă această excepție. Partea Path: $.Comenzi.Client.Comenzi.Client... de la finalul mesajului arată exact proprietățile care formează bucla.

Situația e foarte frecventă cu Entity Framework, unde entitățile au proprietăți de navigare în ambele sensuri, și în API-urile ASP.NET Core care întorc direct entitățile.

Soluții, de la cea mai curată:

  • returnezi un DTO (o clasă sau un record doar cu datele de afișat, fără legături inverse);
  • marchezi legătura inversă cu [JsonIgnore];
  • setezi ReferenceHandler = ReferenceHandler.IgnoreCycles (scrie null în locul buclei) sau ReferenceHandler.Preserve (adaugă $id și $ref în JSON).

Rareori cauza e chiar adâncimea: un obiect legitim cu peste 64 de niveluri, caz în care mărești MaxDepth.

De ce apare: cauzele frecvente

1Legătură inversă serializată

Greșit
C#
class Comanda
{
    public string Produs { get; set; }
    public Client Client { get; set; }
}
Corect
C#
class Comanda
{
    public string Produs { get; set; }
    [JsonIgnore]
    public Client Client { get; set; }
}

[JsonIgnore] (din System.Text.Json.Serialization) exclude proprietatea din JSON, deci bucla dispare.

2Entități EF returnate direct dintr-un API

Greșit
C#
return Ok(await db.Clienti.Include(c => c.Comenzi).ToListAsync());
Corect
C#
return Ok(await db.Clienti
    .Select(c => new { c.Nume, Comenzi = c.Comenzi.Select(o => o.Produs) })
    .ToListAsync());

Un obiect de transfer conține doar datele necesare, fără proprietăți de navigare în ambele sensuri.

3Bucle acceptate prin opțiuni

Greșit
C#
string json = JsonSerializer.Serialize(client);
Corect
C#
var optiuni = new JsonSerializerOptions { ReferenceHandler = ReferenceHandler.IgnoreCycles };
string json = JsonSerializer.Serialize(client, optiuni);

IgnoreCycles scrie null în locul referinței care ar închide bucla. E util când nu poți modifica clasele.

Repară tu

Repară eroarea, direct în pagină

Programul transformă un client cu comenzile lui în JSON, dar se oprește cu System.Text.Json.JsonException: A possible object cycle was detected. Exclude din JSON legătura inversă Comanda.Client, ca programul să afișeze {"Nume":"Ana","Comenzi":[{"Produs":"Laptop"}]}.

Codul care dă eroarea
C#
using System.Text.Json;

var client = new Client { Nume = "Ana" };
client.Comenzi.Add(new Comanda { Produs = "Laptop", Client = client });
Console.WriteLine(JsonSerializer.Serialize(client));

class Client
{
    public string Nume { get; set; }
    public List<Comanda> Comenzi { get; set; } = new();
}

class Comanda
{
    public string Produs { get; set; }
    public Client Client { get; set; }
}
După reparație, programul afișează
{"Nume":"Ana","Comenzi":[{"Produs":"Laptop"}]}
Indiciu

Adaugă using System.Text.Json.Serialization; și atributul [JsonIgnore] pe proprietatea Client din Comanda.

Alte forme ale mesajului

  • Newtonsoft.Json.JsonSerializationException: Self referencing loop detected for property 'Client' with type 'Client'. Path 'Comenzi[0]'.

Cum o eviți pe viitor

  • Nu serializa direct entitățile din baza de date; creează DTO-uri pentru răspunsurile API.
  • Când modelul are legături în ambele sensuri, decide care parte apare în JSON și marchează-o pe cealaltă cu [JsonIgnore].
  • Configurează global ReferenceHandler.IgnoreCycles în ASP.NET Core doar dacă înțelegi ce date se pierd.
  • Citește Path din mesaj: proprietățile care se repetă formează bucla.

Întrebări frecvente

Care e diferența dintre IgnoreCycles și Preserve?

IgnoreCycles scrie null la referința care ar închide bucla și produce un JSON obișnuit. Preserve păstrează referințele prin $id și $ref, dar JSON-ul rezultat e mai greu de folosit pentru clienți care nu cunosc acest format.

De ce apare eroarea abia când adaug Include în Entity Framework?

Pentru că fără Include proprietățile de navigare rămân goale, iar bucla nu există. Când încarci și comenzile, iar fiecare comandă are clientul, obiectele se leagă unele de altele și serializarea intră în buclă.

Erori înrudite

← Toate erorile C#

Tudor Andrei Dumitrescu
Cine a explicat eroarea

Tudor Andrei Dumitrescu

Senior Software Developer · fondatorul Academiei Programatorilor

LinkedIn
  1. 2019 Junior JavaCognizant Softvision
  2. 2021 Mid JavaCognizant Softvision
  3. 2022 Team LeaderEndava
  4. 2023 Senior Software DeveloperUniCredit
  5. Acum Senior Software DeveloperHCLTech
Certificat de absolvire Instructor / Preparator formare, Tudor Andrei Dumitrescu
Certificat de formator autorizatMinisterul Muncii și Ministerul Educației · 2022
Certificat de absolvire Instructor / Preparator formare, Tudor Andrei Dumitrescu

Certificat de formator autorizat · Ministerul Muncii și Ministerul Educației · 2022

Din 2020 construiește Academia Programatorilor, iar din 2026 și JoburiIT.ro. Fiecare eroare de aici a fost reprodusă în editorul nostru: codul greșit chiar dă mesajul din titlu, iar reparația chiar funcționează.

Învață C# de la zero, cu exerciții la fiecare lecție

Curs C#: lecții scurte, fiecare cu un exercițiu verificat automat, direct în browser. Primele 15 lecții sunt gratuite.