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 32. Consider using ReferenceHandler.Preserve on JsonSerializerOptions to support cycles.

JsonException: A possible object cycle was detected

Have you ever encountered the JsonException error message while working with JSON serialization? It can be caused by a cycle in the object graph or if the object depth is larger than the maximum allowed depth of 32.

Object Cycle in JSON Serialization

An object cycle occurs when one JSON object references another object that eventually references the original object, creating a cycle. For example, consider the following JSON:

{
    "name": "John",
    "age": 30,
    "friends": [
        {
            "name": "Mary",
            "age": 28,
            "friends": [
                {
                    "name": "John",
                    "age": 30,
                    "friends": [...] // cycle
                }
            ]
        }
    ]
}

In this example, John and Mary are friends and each other's friend. When trying to serialize this JSON using C#, it will result in a JsonException with the message mentioned above.

Maximum Object Depth Reached

The second possible cause of this exception is when the object depth is larger than the maximum allowed depth of 32. This can happen when an object has too many nested objects or arrays. To solve this issue, you can increase the maximum allowed depth by setting the MaxDepth property on JsonSerializerOptions:

var options = new JsonSerializerOptions
{
    MaxDepth = 64
};

Solution - Using ReferenceHandler.Preserve on JsonSerializerOptions

The most common solution to resolve the JsonException error message is to use ReferenceHandler.Preserve on JsonSerializerOptions to support cycles. This setting preserves object references when serializing and deserializing JSON, avoiding the creation of object cycles. Here's how to implement it:

var options = new JsonSerializerOptions
{
    ReferenceHandler = ReferenceHandler.Preserve
};

With this setting, when serializing or deserializing a JSON object with a cycle, the reference to the already serialized object is used instead of creating a new object. This ensures that the object graph is not circular and avoids the JsonException error message.

Conclusion

JsonException with the message "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 32. Consider using ReferenceHandler.Preserve on JsonSerializerOptions to support cycles." can be caused by a cycle in the object graph or when the object depth is larger than 32. The most common solution to resolve this issue is to use ReferenceHandler.Preserve on JsonSerializerOptions to support cycles.