n8n-connections

n8n の接続

n8n の SDK には、シンプルな接続構文があります。そのうち 2 つの形式では、検証を通過するものの、ワークフローがひそかに壊れてしまいます。このスキルでは主に、そうした落とし穴を避ける方法を説明します。

絶対に守ること：.to() の落とし穴

.to() は .add() の中に記述し、後ろに続けてはいけません。

.add(node.output(0)).to(target)      // ❌ connection silently dropped
.add(node.output(0).to(target))      // ✅

validate_workflow ではこれを検出できません。ワークフローは検証に通り、公開され、実行されますが、ワイヤーは接続されません。このバグは、ノードの設定ミスや「起動しない」ノードとまったく同じように見えます。

.add(...).to(...) を括弧の外に記述した場合、バグです。例外はありません。

汎用的な接続パターン

次の形式で、IF／Switch の分岐、エラー出力、マージ入力、汎用的な複数 I/O をすべて扱えます。

.add(source.output(n).to(target))

• source.output(n)：出力を選択します（0 始まり）
• .to(target)：接続先を選択します（デフォルトの入力は 0）
• .to(target.input(m))：接続先の特定の入力を選択します（0 始まり）

ワイヤーごとに .add() を 1 回呼び出します。ファンアウトするには、.add() を繰り返します。

判断フロー

Wiring a connection?
├── Linear (one source → one target, single output, single input)?
│   └── .add(source).to(target). The simple case; .to() outside is fine here
│       because there's no .output(n) selector inside .add()
│
├── Selector involved (.output(n) or composite handlers)?
│   └── .to() MUST go inside .add(). See "the trap" above
│
├── Targeting a specific input slot on a multi-input node (Merge)?
│   └── .add(source.output(n).to(target.input(m)))
│       AND check useDataOfInput. See references/MERGE_INDEX_RULES.md
│
├── Error branch?
│   └── .add(node.output(1).to(handler))
│       AND set onError: 'continueErrorOutput' on the node config.
│       See references/ERROR_OUTPUTS.md
│
└── Fan-out (one source → many targets) or fan-in (many sources → one target)?
    └── See references/FAN_OUT_FAN_IN.md

複合ハンドラー（.onTrue、.onFalse、.onCase、.onError）

SDK には、IF、Switch、およびエラー出力を持つすべてのノードで使える便利なハンドラーが用意されています。

.add(ifNode.onTrue(targetA))     // same as .add(ifNode.output(0).to(targetA))
.add(ifNode.onFalse(targetB))    // same as .add(ifNode.output(1).to(targetB))
.add(sw.onCase(2, target))       // same as .add(sw.output(2).to(target))
.add(node.onError(handler))      // same as .add(node.output(1).to(handler))

これらは .output(n) の呼び出しと競合せずに組み合わせられます。

.add(ifNode.onTrue(targetA))
.add(ifNode.output(0).to(targetB))
// Result: BOTH targetA and targetB on IF's main[0]. Composite + .output(n) merge.

避けるべき形式は、上記の .add(selector).to(target) の落とし穴だけです。複合ハンドラーを先に実行したかどうかにかかわらず、これは常に誤りです。

作成または更新のたびに検証する

ワイヤーが欠けていても、validate_workflow は有効と報告します。create_workflow_from_code または update_workflow の後に get_workflow_details で取得し、connections オブジェクトを確認してください。

• 各 main[i] に、想定される接続先の集合が含まれている（ファンアウトが維持され、集約されていない）。
• マージ入力が正しいインデックスに接続され、useDataOfInput が配線と一致している。
• エラー出力を持つノードに onError: 'continueErrorOutput' が設定され、かつ main[1] がハンドラーに接続されている。

いずれかの確認に失敗した場合、検証に通っていてもワークフローは壊れています。修正して再度更新してください。

作成後のチェックリスト全体については、references/VERIFICATION.md を参照してください。

リファレンスファイル

状況に合ったファイルを読んでください。すべて読む必要はありません。

ファイル	読むタイミング
references/FAN_OUT_FAN_IN.md	1 つのソースから複数の接続先へ接続する場合、または複数のソースから 1 つの接続先へ接続する場合
references/MERGE_INDEX_RULES.md	Merge ノードを接続する場合、またはノード設定に useDataOfInput がある場合
references/ERROR_OUTPUTS.md	個々のノードにエラー処理を追加する場合（エラーワークフローの場合は n8n-error-handling を参照）
references/VERIFICATION.md	複雑な接続を含むワークフローを作成または更新した直後

アンチパターン

アンチパターン	問題	修正方法
.add(node.output(0)).to(target)	ワイヤーがひそかに破棄され、検証には通る	.to() を .add() の中に移動する
useDataOfInput: "2" と .input(2) の併用	インデックスが 1 つずれ、ワイヤーが誤った入力に接続される	useDataOfInput: "N" の場合は .input(N - 1) を使う。MERGE_INDEX_RULES.md を参照
onError: 'continueErrorOutput' を設定せずにエラー分岐を接続する	分岐に到達できず、エラー発生時にノードがワークフロー全体を失敗させる	ノード設定に onError: 'continueErrorOutput' を設定する
作成後に get_workflow_details を省略する	壊れたワークフローが気付かれないまま公開される	作成または更新の後は必ず取得して確認する
1 つの接続を配線する前に 4 つすべてのリファレンスファイルを読む	コンテキストを無駄に消費する	状況に合ったファイルだけを読む