n8n-node-configuration-official

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-ai-nodes-official に委ねます
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-official を参照してください	必ず認証情報を使用してください
設定後に test_workflow でノードをテストしない	実行時エラーが実データでしか表面化しません	公開前に、必ずピン留めしたデータでテストしてください