A service logs incoming requests and one day throws "TypeError: Converting circular structure to JSON". What exactly causes JSON.stringify to throw this, and how do you make such an object serializable?

## What the algorithm actually does Serialization is a depth-first traversal that emits text as it descends. To detect the impossible case, it maintains a stack of the objects currently being serialized. Before descending into an object or array it checks whether that value is already on the stack; if it is, the walk has re-entered something it never left, so no finite output exists, and the specification requires a `TypeError`. Engines add a helpful message — V8 says `Converting circular structure to JSON` and, in recent versions, prints the property path and the two points where the cycle closes. ```js const node = { name: 'root' }; node.self = node; JSON.stringify(node); // TypeError ``` ## Cycles, not duplicates The distinction that separates people who have read the algorithm from people who have guessed: the check is against the **current ancestor path**, and the object is popped off that stack when its subtree finishes. So a shared reference that is not an ancestor is perfectly legal: ```js const shared = { id: 1 }; JSON.stringify({ a: shared, b: shared }); // '{"a":{"id":1},"b":{"id":1}}' ``` The object is written out twice. That is a size problem and it means the parsed result has two distinct objects where you had one, but it is not an error. Only reachability from a node back to itself throws. ## Why real objects have cycles Almost every rich runtime object graph does: - A server request object holds a reference to its socket, and the socket holds the request. - A parsed tree node holds its children and each child holds a `parent`. - A framework's context object holds the request, which holds the context. - A cached entry holds the collection it lives in. - Two domain entities model a bidirectional relationship — an order holds its customer, the customer holds their orders. This is why the error so often appears in logging code. Nobody set out to serialize a socket; somebody logged `req` "just in case" and the object graph did the rest. ## Fix one: stop serializing the graph The first question to ask is what you actually wanted in that text. For a log line it is a handful of fields: ```js log(JSON.stringify({ method: req.method, path: req.url, requestId: req.id, userId: req.user?.id, })); ``` This is better on every axis: it cannot throw, its size is bounded, it does not leak headers or credentials that happened to be hanging off the object, and the output shape is stable enough to query. An allowlist replacer (`JSON.stringify(req, ['method', 'url'])`) expresses the same intent when the fields are top-level. ## Fix two: a cycle-tolerant replacer When you genuinely need a generic dump — a debug endpoint, a crash reporter — track what you have seen: ```js function safeStringify(value, space) { 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; }, space); } ``` This works, and it is worth being honest about what it changes. A `WeakSet` that is never pruned is **stricter than the specification**: it marks any repeated object, including the harmless diamond above, so shared-but-acyclic references also become `'[Circular]'`. Matching the real semantics requires tracking the ancestor path and removing entries as the walk unwinds, which the replacer's top-down callback cannot do on its own — it is never told when a subtree ends. For debug output the stricter behaviour is usually fine, and arguably desirable, since it also bounds the output size. Note also that the substitute changes the value's *type* from object to string, so a consumer with a schema will reject it. ## Fix three: use a structural clone where that is the real intent If what you wanted was a deep copy rather than text, `structuredClone` handles cycles natively and preserves them in the copy, along with several types that serialization cannot carry. It is not an interchange format and produces no text, so it does not help you send anything — but a surprising number of "circular structure" errors come from code that was using stringify/parse as a deep-copy idiom in the first place. ## Diagnosing it in production The stack trace points at your logging call, not at the cycle. In a V8 runtime, read the error message itself: it names the property path from the root to the offending reference. If the message is not detailed enough, reproduce with the `safeStringify` above and look for where `'[Circular]'` appears — that is the closing edge. Then apply fix one to that call site, because a generic dump of a runtime object is nearly always the wrong thing to log even when it does not throw.