本文へ移動
プログラミング大全動かして、比べて、理解する。

JavaScript / コードを試す

TypeError: Converting circular structure to JSON

自分自身を辿れるオブジェクトを JSON.stringify() に渡すと出ます。親子の相互参照、 DOM 要素、通信のオブジェクト。どこで輪になっているかの見つけ方と、3つの直し方を載せています。

固定例はNode 24.22.3の実行記録を照合しています()。下の入力欄の結果は今回の実行で確認してください。

同じエラー名でも原因は異なります。発生した行とその時点の値を確かめ、該当する修正例へ進んでください。

元の教材を読む(別タブ)

コードを編集して試す

ブラウザー内で実行します。コードの送信・自動実行・自動保存はしません。このタブを閉じると入力は失われます。機密情報は入力しないでください。

playground.js

8,192 UTF-8 byte・実行1.5秒・出力60行/8KiB以内。Ctrl / ⌘ + Enterでも実行できます。

パネルを開くと編集できます。

現在の入力は未実行です。

今回の実行結果
JavaScriptUTF-8 · LF

実行画面や検索画面の間の通常クリックでは入力をこのタブのRAMで保持します。元の教材は別タブで開きます。再読み込み・タブ終了ではRAMの入力は失われます。

自分自身に辿り着けるオブジェクトを文字列にしようとしたときに出ます。

javascript失敗・注意の例

const node = { name: 'a' };

node.self = node;

JSON.stringify(node);
固定例の期待出力 · Node 24.22.3
TypeError: Converting circular structure to JSON
    --> starting at object with constructor 'Object'
    --- property 'self' closes the circle
表示用コードUTF-8 · LF

self を辿るとまた node に戻るので、終われません。

2行目から後ろは、どこで輪になったかを教えてくれる補足です。処理系によって出方が違います。

実務でいちばん多い形:親と子がお互いを持つ

javascript失敗・注意の例

const parent = { name: '親' };
const child = { name: '子', parent };

parent.child = child;

JSON.stringify(parent);
固定例の期待出力 · Node 24.22.3
TypeError: Converting circular structure to JSON
    --> starting at object with constructor 'Object'
    |     property 'child' -> object with constructor 'Object'
    --- property 'parent' closes the circle
表示用コードUTF-8 · LF

parent → child → parent で輪になっています。 補足の行を上から読むと、どの鍵で戻ったかが分かります。

同じものが2回出るだけなら平気

example.js

const shared = { n: 1 };

console.log(JSON.stringify({ a: shared, b: shared }));
固定例の期待出力 · Node 24.22.3
{"a":{"n":1},"b":{"n":1}}
表示用コードUTF-8 · LF

同じものを2か所から指しているだけなら落ちません。 中身が2回書き出されるだけです。

問題になるのは自分に戻ってこられるときだけです。

直し方1: 要らない側を落とす

いちばん簡単で、たいてい正しい方法です。

example.js

const parent = { name: '親' };
const child = { name: '子', parent };

parent.child = child;

console.log(JSON.stringify(child, (key, value) => (key === 'parent' ? undefined : value)));
固定例の期待出力 · Node 24.22.3
{"name":"子"}
表示用コードUTF-8 · LF

第2引数の関数(置換関数)が、すべての鍵について呼ばれます。 undefined を返した鍵は出力から消えます。

送りたい形が決まっているなら、最初から作り直すほうが確実です。

example.js

const parent = { name: '親' };
const child = { name: '子', parent };

parent.child = child;

console.log(JSON.stringify({ name: child.name, parentName: child.parent.name }));
固定例の期待出力 · Node 24.22.3
{"name":"子","parentName":"親"}
表示用コードUTF-8 · LF

「全部送って、受け取る側で選ぶ」をやめると、この問題は起きません。

直し方2: 通ったものを覚えて切る

構造が分からないものを、とりあえずログに出したいときに使います。

example.js

const node = { name: 'a' };

node.self = node;

const seen = new WeakSet();

console.log(
  JSON.stringify(node, (key, value) => {
    if (typeof value === 'object' && value !== null) {
      if (seen.has(value)) return '[循環]';
      seen.add(value);
    }
    return value;
  }),
);
固定例の期待出力 · Node 24.22.3
{"name":"a","self":"[循環]"}
表示用コードUTF-8 · LF

落ちなくなりますが、情報は欠けます。 記録や調査のためだけに使ってください。

WeakSet を使うと、覚えたオブジェクトが後片付けの邪魔になりません。同じ理由で Set より向いています。

直し方3: 複製したいだけなら structuredClone()

JSON を経由するのが目的でないなら、そもそも JSON.stringify() は要りません。

example.js

const node = { name: 'a' };

node.self = node;

const copied = structuredClone(node);

console.log(copied.name);
console.log(copied.self === copied);
console.log(copied === node);
固定例の期待出力 · Node 24.22.3
a
true
false
表示用コードUTF-8 · LF

structuredClone() は循環をそのまま保って複製します。 別のオブジェクトになり、輪の形も残ります。

→ オブジェクトを結合する

直し方4: toJSON() を持たせる

そのオブジェクトを送るたびに同じ形にしたいなら、こちらです。

example.js

class TreeNode {
  constructor(name) {
    this.name = name;
    this.children = [];
  }

  add(child) {
    this.children.push(child);
    child.parent = this;
    return this;
  }

  toJSON() {
    return { name: this.name, children: this.children };
  }
}

const root = new TreeNode('根');

root.add(new TreeNode('子'));

console.log(JSON.stringify(root));
固定例の期待出力 · Node 24.22.3
{"name":"根","children":[{"name":"子","children":[]}]}
表示用コードUTF-8 · LF

JSON.stringify() は、toJSON() があればその戻り値を使います。 parent は返していないので、輪になりません。

呼ぶ側は何も書かなくてよいので、忘れようがないのが利点です。 → class — 作る・継承する・隠す

そもそも輪にしない

保存や送信をするデータなら、親を持たせずに id で指すほうが素直です。

example.js

const rows = [
  { id: 1, name: '根', parentId: null },
  { id: 2, name: '子', parentId: 1 },
];

console.log(JSON.stringify(rows));
固定例の期待出力 · Node 24.22.3
[{"id":1,"name":"根","parentId":null},{"id":2,"name":"子","parentId":1}]
表示用コードUTF-8 · LF

表に入る形と同じです。受け取った側で木に組み直します。 循環は「画面で使うための形」であって、送るための形ではありません。

配列でも起きる

javascript失敗・注意の例

const list = [1];

list.push(list);

JSON.stringify(list);
固定例の期待出力 · Node 24.22.3
TypeError: Converting circular structure to JSON
    --> starting at object with constructor 'Array'
    --- index 1 closes the circle
表示用コードUTF-8 · LF

配列のときは、鍵の名前ではなく添字が出ます。

ついでに:落ちないのに消えるもの

javascript失敗・注意の例

console.log(JSON.stringify({ m: new Map([['a', 1]]), s: new Set([1]) }));
固定例の期待出力 · Node 24.22.3
{"m":{},"s":{}}
表示用コードUTF-8 · LF

Map と Set は、落ちませんが中身が消えます。 配列にしてから渡してください。

example.js

console.log(JSON.stringify({ m: [...new Map([['a', 1]])], s: [...new Set([1])] }));
固定例の期待出力 · Node 24.22.3
{"m":[["a",1]],"s":[1]}
表示用コードUTF-8 · LF

→ Map と Set

どこで起きやすいか

出どころ 何が輪になるか
親子の木構造 子が親を持っている
DOM の要素 要素が親要素・文書・窓を辿れる
通信ライブラリの応答 応答が要求を持ち、要求が応答を持つ
エラーに付けた文脈 例外に付けたオブジェクトが例外を指す

ログを送ろうとして落ちるのが、いちばんよくある出会い方です。

エラーをそのまま JSON.stringify() に渡すのも、別の理由で失敗します。

javascript失敗・注意の例

console.log(JSON.stringify(new Error('壊れた')));
固定例の期待出力 · Node 24.22.3
{}
表示用コードUTF-8 · LF

→ Error と try / catch / finally / throw

探しかたの順序

  1. 文言の2行目から後ろを読む。 どの鍵で戻ったかが書いてある
  2. その鍵が本当に要るか考える。たいてい要らない
  3. 要らないなら置換関数で落とすか、送る形を作り直す
  4. 中身が分からないものをとりあえず出したいなら、通ったものを覚えて切る
  5. 複製が目的なら structuredClone() に替える

実行結果は、記事冒頭に示したNodeの版で確認しています。文言は処理系と版によって変わります。補足の行が出ない処理系もあります。

まとめ

  • 自分に戻ってこられる形だけが問題。同じものを2か所から指すのは平気
  • 文言の2行目から後ろに、どの鍵で輪になったかが出る
  • 直し方は要らない鍵を落とす・通ったものを覚えて切る・toJSON() を持たせる・structuredClone()
  • Map と Set は落ちないが中身が消える
  • 送る形を最初から作るのがいちばん確実
  • JSON.stringify(error) は落ちないが {} になる

出典

この教材の原文(Markdown・別タブ)