{
  "id": "dotnet/serialization-cycle-detected",
  "signature": "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.",
  "signature_zh": "System.Text.Json.JsonException: 检测到可能的对象循环。这可能是由于循环或对象深度大于允许的最大深度 64。考虑在 JsonSerializerOptions 上使用 ReferenceHandler.Preserve 来支持循环。",
  "regex": "A possible object cycle was detected",
  "domain": "dotnet",
  "category": "data_error",
  "subcategory": null,
  "root_cause": "The JSON serializer encountered a circular reference (e.g., a parent referencing a child that references the parent) during serialization, which it cannot handle by default in System.Text.Json.",
  "root_cause_type": "generic",
  "root_cause_zh": "JSON 序列化器在序列化过程中遇到了循环引用（例如，父对象引用子对象，子对象又引用父对象），而 System.Text.Json 默认无法处理这种情况。",
  "versions": [
    {
      "version": "net6.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "net7.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "net8.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "net9.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "Setting MaxDepth to a very high value (e.g., 1024)",
      "why_fails": "This only increases the depth limit but does not resolve the cycle; the serializer will still throw an exception when it detects the cycle at any depth.",
      "fail_rate": 0.9,
      "condition": "",
      "sources": []
    },
    {
      "action": "Using Newtonsoft.Json instead of System.Text.Json without configuring ReferenceLoopHandling",
      "why_fails": "Newtonsoft.Json also throws an error by default on cycles unless ReferenceLoopHandling.Ignore is set, so simply switching libraries does not fix the issue.",
      "fail_rate": 0.85,
      "condition": "",
      "sources": []
    },
    {
      "action": "Adding [JsonIgnore] on all navigation properties randomly",
      "why_fails": "This may remove necessary data and break API contracts; a targeted approach is needed to identify the specific cycle.",
      "fail_rate": 0.75,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Use ReferenceHandler.Preserve in JsonSerializerOptions. Example: 'var options = new JsonSerializerOptions { ReferenceHandler = ReferenceHandler.Preserve }; var json = JsonSerializer.Serialize(obj, options);' This adds $id and $ref metadata to handle cycles.",
      "success_rate": 0.95,
      "how": "Use ReferenceHandler.Preserve in JsonSerializerOptions. Example: 'var options = new JsonSerializerOptions { ReferenceHandler = ReferenceHandler.Preserve }; var json = JsonSerializer.Serialize(obj, options);' This adds $id and $ref metadata to handle cycles.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Apply [JsonIgnore] on the property causing the cycle. For example, if 'Order.Customer' references 'Customer.Orders', add '[JsonIgnore]' on 'Customer.Orders' in the DTO or view model.",
      "success_rate": 0.9,
      "how": "Apply [JsonIgnore] on the property causing the cycle. For example, if 'Order.Customer' references 'Customer.Orders', add '[JsonIgnore]' on 'Customer.Orders' in the DTO or view model.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Use Data Transfer Objects (DTOs) that flatten the object graph and avoid circular references. For example, create 'OrderDto' with 'CustomerId' instead of a full 'Customer' object.",
      "success_rate": 0.85,
      "how": "Use Data Transfer Objects (DTOs) that flatten the object graph and avoid circular references. For example, create 'OrderDto' with 'CustomerId' instead of a full 'Customer' object.",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "Use ReferenceHandler.Preserve in JsonSerializerOptions. Example: 'var options = new JsonSerializerOptions { ReferenceHandler = ReferenceHandler.Preserve }; var json = JsonSerializer.Serialize(obj, options);' This adds $id and $ref metadata to handle cycles.",
    "Apply [JsonIgnore] on the property causing the cycle. For example, if 'Order.Customer' references 'Customer.Orders', add '[JsonIgnore]' on 'Customer.Orders' in the DTO or view model.",
    "Use Data Transfer Objects (DTOs) that flatten the object graph and avoid circular references. For example, create 'OrderDto' with 'CustomerId' instead of a full 'Customer' object."
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://learn.microsoft.com/en-us/dotnet/standard/serialization/system-text-json/preserve-references",
  "official_doc_section": null,
  "error_code": null,
  "verification_tier": "ai_generated",
  "confidence": 0.85,
  "fix_success_rate": 0.9,
  "resolvable": "true",
  "first_seen": "2023-02-14",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}