n8n-node-configuration

n8n ノードの設定

n8n の各ノードには、それぞれ固有のパラメーター構造があり、多くの場合、条件付きフィールドがあります（パラメーター X は、パラメーター Y の値が Z の場合にのみ有効です）。構造はバージョンによって変わります。推測すると、不可解な検証エラーが発生します。

推測せず、get_node_types ツールを使用してください。

必須事項

ノードを設定する前に、識別子（resource、operation、mode）を指定して get_node_types を呼び出してください。 識別子を指定しないと、操作固有のパラメーターや必須フィールドが欠けた汎用的な構造が返されます。正確な構造に基づいて設定してください。記憶を頼りに推測しないでください。

実行時の get_node_types 出力が、正式なパラメーター構造です。 このスキルのリファレンスで説明するのは、パターン、注意点、セキュリティルール、判断方法（どの操作を使うか、テキストフィールドより認証情報を使う理由、エンジンの再試行上限など）であり、パラメーター名やフィールド構造ではありません。リファレンスの例と get_node_types の出力が異なる場合は、ツールの出力を優先してください。Markdown の記述は古くなることがありますが、型定義は実際のソースから生成されます。

リソースロケーターや読み込みオプションの値を推測しないでください。 get_node_types が @searchListMethod または @loadOptionsMethod を持つパラメーター（Slack のチャンネル、Sheets のタブ／ドキュメント、DB のテーブル／列、モデルのリスト、ラベルなど）を示す場合は、explore_node_resources を使って実際の値を解決してください（list_credentials から取得した credentialId を渡します）。返された value を使用してください。正確な ID がすでにわかっている場合は、それを使用してください。複数の候補が一致し、意図が不明確な場合は、ユーザーに確認してください。架空の ID は検証に通っても、何も指し示しません。例外：toolWorkflow.workflowId には検索メソッドがないため、search_workflows で解決し、mode: 'id' を使用してください。

基本方針

• まず操作を設定します。 最初に resource と operation を設定すると、条件付きパラメーターが表示されます。「フィールドが存在しない」というエラーの多くは、実際には「親操作をまだ設定していない」ということです。
• 操作間でパラメーターを引き継がないでください。 operation を変更する場合は、新しい構造から設定し直してください。前の操作の古いパラメーターが検証エラーの原因になります。

新しいノードを追加する場合の手順

1. search_nodes(['<capability keyword>'])
   → returns matching node IDs + discriminators
2. Pick the right (resource, operation) for the task.
3. get_node_types([{ name: '...', resource: '...', operation: '...' }])
   → returns exact parameter shape including conditional fields
4. For any RLC / load-options param in that shape, ground the real value:
   explore_node_resources({ nodeType, version, methodName, methodType, credentialType, credentialId, currentNodeParameters? })
   → use a returned `value`. Don't invent IDs.
5. Build the node config from that shape.
6. validate_workflow → fix errors.
7. get_workflow_details → inspect the saved config; confirm parameters landed.
8. test_workflow with pinned data → confirm runtime behavior.

手順を飛ばすと、その後の手順に影響が積み重なります。最もよくあるのは手順 3 を飛ばすことで、その結果、「識別子を渡していない」ことが原因の「Cannot read property X」エラーが発生します。

サイドチャネルとしての validate_node_config

validate_node_config([{ type, typeVersion, parameters, isToolNode? }]) は、分離したノード設定に対して validate_workflow と同じ Zod スキーマを実行します。これはスキーマレベルの検証に限られ、validate_workflow に代わるものではありません（公開前の最終チェックには引き続き validate_workflow が必要です）。次の用途では、より明確な結果が得られます。

• 構築中の単一ノードを繰り返し調整する場合。 変更のたびに validate_workflow を再実行するよりも高速です。
• 既存のワークフローを少し変更する場合。 配線に変更がなければ、変更したノードだけを確認し、公開前に全体を検証してください。
• 設定ミスのあるノードをデバッグする場合。 グラフの情報に埋もれることなく、パラメーターごとのエラーを確認できます。

ai_tool 経由で接続されるツールサブノードでは、正しい displayOptions 分岐が評価されるように isToolNode: true を設定してください。

操作に応じた設定

ほとんどのノードの最上位の構造は、次のようになっています。

{
  resource: '<thing being operated on>',   // 'message', 'spreadsheet', 'user', etc.
  operation: '<verb>',                      // 'send', 'append', 'lookup', etc.
  // ...operation-specific parameters
}

(resource, operation) の組み合わせによって、存在する他のパラメーターが決まります（例：Slack の (message, send) と (user, info) では、パラメーターが異なります）。

手順：

1. まず resource と operation を設定します。
2. 最初に識別子を指定していなかった場合は、指定して get_node_types を再度取得します。
3. 操作固有の構造に基づいて、残りの項目を設定します。

プロパティの依存関係：見落としやすい落とし穴

一部のパラメーターは、分かりにくい形でほかのパラメーターに依存します。

• あるフィールドは、別のフィールドが特定の値の場合にのみ必須になります。
• あるフィールドで、モードに応じて異なる型が許可されます。
• あるフィールドの選択肢が、別のフィールドの値によって決まります。

例：

• HTTP Request の authentication: 'genericCredentialType' には genericAuthType と credentials が必要ですが、'predefinedCredentialType' では異なる形式が必要です。
• Postgres の operation: 'executeQuery' には query が必要ですが、operation: 'select' には table と columns が必要です。
• Slack では、messageType: 'block' にすると、messageType: 'text' にはないブロックビルダー用のフィールドが有効になります。

特定の操作について、必ず get_node_types で確認してください。別の操作の設定を流用しても、検証に通るとは限りません。

別のフィールドに応じて選択肢が変わるものは、@loadOptionsMethod です。explore_node_resources（methodType: 'loadOptions'）で現在の選択肢を取得し、そのメソッドが依存する場合は、前に選択した値を currentNodeParameters で渡してください（例：スプレッドシートのタブ一覧の取得には documentId が必要です）。

リファレンスファイル

カテゴリごとの注意点です。設定するノードの種類に応じてファイルを読んでください。

ファイル	読むタイミング
references/HTTP_NODES.md	HTTP Request の設定時：認証、ページネーション、クエリ／本文パラメーター、リトライ
references/WEBHOOK_NODES.md	Webhook トリガーまたは Respond to Webhook の設定時：本文の解析、レスポンス形式、非同期パターン
references/COMMS_NODES.md	Slack、Gmail、Discord、メールの設定時：認証情報の種類、メッセージ形式、添付ファイル
references/DATABASE_NODES.md	Postgres、MySQL、Mongo、Supabase の設定時：クエリと操作の違い、パラメーターのバインド、エラー処理
references/AI_NODES.md	AI Agent ノードの設定項目：ストリーミング、ビジョン、maxIterations、モデルサブノードでのリトライ。設計（プロンプト、ツール、メモリー、構造化出力）については n8n-agents を参照してください
references/TRIGGER_NODES.md	Webhook、Schedule、Manual、Execute Workflow Trigger の設定時：入力スキーマ、ポーリングとリアルタイムの違い
references/SWITCH_FALLBACK.md	Switch ノードの設定時：名前のない出力やフォールバックの欠落により、一致しないアイテムが通知されずに破棄されます
references/MERGE_NODE.md	Merge ノードの設定時、または useDataOfInput、numberOfInputs、ブランチの合流が出てきたとき

アンチパターン

アンチパターン	問題点	対処法
ノードの設定を、昨年のノードの見た目の記憶を頼りに作成する	パラメーター形式が変わっていて、分かりにくいエラーで検証に失敗します	セッションごと、ノードごとに必ず get_node_types を使ってください
get_node_types で識別子を指定しない	汎用的な形式しか取得できず、操作固有の必須フィールドを見落とします	必ず resource と operation（存在する場合は mode も）を渡してください
ある操作のノード設定を別の操作にコピーして手を加える	古いパラメーターが検証に引っかかり、条件付きフィールドも適用されません	新しい操作の形式を基に設定を作り直してください
ノードのテキストフィールドにトークンや認証情報をハードコードする	エクスポート時に漏えいします。n8n-credentials-and-security を参照してください	必ず認証情報を使用してください
設定後に test_workflow でノードをテストしない	実行時エラーは実データでしか表面化しません	公開前に、必ず固定データでテストしてください