Fix: JSON Circular Reference (Converting Circular Structure to JSON)

What Is a Circular Reference?

A circular reference is created when an object's property chain loops back to itself. The simplest example:

const obj = { name: "Alice" };
obj.self = obj; // circular reference!

JSON.stringify(obj);
// TypeError: Converting circular structure to JSON
//   --> starting at object with constructor 'Object'
//   --- property 'self' closes the circle

Circular references appear frequently with DOM nodes, Express req/res objects, Mongoose documents with populated references, and complex class instances that hold parent references.

Solution 1: Custom Replacer Function

The cleanest approach for most cases. Pass a replacer to JSON.stringify() that tracks visited objects and replaces cycles with a sentinel string:

function getCircularReplacer() {
  const seen = new WeakSet();
  return (key, value) => {
    if (typeof value === "object" && value !== null) {
      if (seen.has(value)) return "[Circular]";
      seen.add(value);
    }
    return value;
  };
}

const obj = { name: "Alice" };
obj.self = obj;

JSON.stringify(obj, getCircularReplacer(), 2);
// {
//   "name": "Alice",
//   "self": "[Circular]"
// }

Solution 2: Cycle-Safe Stringify Helper

If you need a drop-in replacement for JSON.stringify() that never throws on cycles, wrap it in a reusable helper:

function safeStringify(value, indent = 2) {
  const seen = new WeakSet();
  return JSON.stringify(
    value,
    (key, val) => {
      if (typeof val === "object" && val !== null) {
        if (seen.has(val)) return "[Circular]";
        seen.add(val);
      }
      return val;
    },
    indent
  );
}

// Works even on deeply nested cycles
const tree = { id: 1, children: [] };
tree.children.push({ id: 2, parent: tree }); // cycle via parent

console.log(safeStringify(tree));

Solution 3: Break the Cycle Before Serialising

If you control the data structure, the cleanest fix is to never create the cycle in the first place. Use structuredClone() to deep-clone the object and then manually delete the circular property:

const original = { name: "Alice", parent: null };
original.self = original; // circular

// structuredClone handles cycles when cloning
const clone = structuredClone(original);
delete clone.self; // remove the reference you don't need in JSON

JSON.stringify(clone, null, 2);
// { "name": "Alice", "parent": null }

Comparison of Approaches