How to fix broken variable interpolation in system prompts in n8n?

To fix broken variable interpolation in system prompts in n8n, you need to modify the JSON schema of the node in question. This typically involves updating the system prompt field to properly handle variable interpolation, ensuring that variables enclosed in curly braces (e.g., {{$parameter}}) are correctly processed.

 
Step 1: Identify the Root Cause
 

Before attempting to fix the issue, it's important to understand why variable interpolation might be broken in your n8n system prompts. Common causes include:

• Incorrect syntax in the variable references
• Issues with the JSON schema definition for the node
• Conflicts between n8n's templating system and other templating languages
• Version compatibility issues

Variable interpolation in n8n allows you to dynamically insert values from other nodes or workflow data into your prompts, using the syntax {{$node["NodeName"].data["field"]}} or similar patterns.

 
Step 2: Check Your Variable Syntax
 

First, verify that you're using the correct syntax for variable interpolation:

{{$node["PreviousNode"].data["outputField"]}}

For JSON data or objects, you might need to access nested properties:

{{$node["PreviousNode"].json\["property"]\["nestedProperty"]}}

Ensure you're using the correct reference method depending on your data structure.

 
Step 3: Update the Node's JSON Schema
 

If the basic syntax checks don't resolve the issue, you may need to modify the node's JSON schema. This approach is especially relevant if you're creating or modifying custom nodes:

{
  "name": "yourNodeName",
  "properties": [
    {
      "displayName": "System Prompt",
      "name": "systemPrompt",
      "type": "string",
      "typeOptions": {
        "rows": 5,
        "editor": "codeEdit",
        "editorLanguage": "json"
      },
      "default": "",
      "noDataExpression": false,  // Set this to false to enable expressions
      "description": "The system prompt to use"
    }
  ]
}

The crucial part is setting "noDataExpression": false to ensure that variable interpolation is enabled for this field.

 
Step 4: Fix Escaping Issues in System Prompts
 

Sometimes, the issue might be related to special characters or escaping. For JSON-based system prompts, use proper escaping:

{
  "role": "system",
  "content": "Your name is {{$parameter["name"]}} and your task is {{$parameter["task"]}}"
}

Note how the quotes inside the interpolation expression are escaped with backslashes.

 
Step 5: Handle Multiline Prompts Correctly
 

If your system prompt contains multiple lines, ensure they're properly formatted in the JSON:

{
  "role": "system",
  "content": "This is line one.\nThis is line two with variable {{$node["Input"].json["value"]}}.\nThis is line three."
}

Use \n for line breaks in JSON strings.

 
Step 6: Test with Expression Editor
 

n8n provides an expression editor that can help debug variable interpolation issues:

• Click on the field where you're experiencing the issue
• Click the "gears" icon to open the Expression Editor
• Test your expressions directly in this editor to see if they resolve correctly
• Use the "Preview" feature to see how the expressions will be evaluated

This can help identify syntax errors or reference issues.

 
Step 7: Check for Double Curly Brace Conflicts
 

Some nodes (especially those that interact with systems that use similar templating systems like Handlebars, Mustache, etc.) might have conflicts with the double curly brace syntax. In such cases, you might need to use a different approach:

// Instead of:
"Your variable is {{$node["Input"].json["value"]}}"

// Use expression mode directly (by clicking the gears icon):
=$node["Input"].json["value"]

This approach bypasses the template system altogether.

 
Step 8: Implement a Custom Function for Complex Cases
 

For more complex interpolation needs, you can use the Function node to prepare your prompt:

// In a Function node
const inputData = $input.item.json;
const systemPrompt = {
  role: "system",
  content: `Your name is ${inputData.name} and your task is ${inputData.task}`
};

return { json: { systemPrompt } };

Then use the output of this Function node in your system prompt field.

 
Step 9: Update n8n to the Latest Version
 

Some interpolation issues have been fixed in newer versions of n8n. Ensure you're running the latest version:

# If using npm:
npm update n8n -g

# If using Docker:
docker pull n8nio/n8n:latest

After updating, restart your n8n instance to apply the changes.

 
Step 10: Debug Using Workflow Console
 

You can use the built-in console to debug variable interpolation issues:

// In a Function node
console.log('System Prompt before interpolation:', {{$parameter["systemPrompt"]}});
console.log('Variable value:', $node["Input"].json["value"]);

return $input.item;

Execute the workflow and check the execution log to see the values.

 
Step 11: Check for Encoding Issues
 

Sometimes, variable interpolation fails due to encoding issues, especially with special characters or non-ASCII text. Try encoding/decoding your variables:

// In a Function node
const rawValue = $node["Input"].json["value"];
const encodedValue = encodeURIComponent(rawValue);
// Use encodedValue in your prompt, or decode it later if needed
const decodedValue = decodeURIComponent(encodedValue);

return { json: { encodedValue, decodedValue } };

 
Step 12: Handle Arrays and Complex Objects
 

If you're trying to interpolate arrays or complex objects, convert them to strings first:

// For arrays
const arrayAsString = $node["Input"].json["array"].join(", ");

// For objects
const objectAsString = JSON.stringify($node["Input"].json["object"]);

return { json: { arrayAsString, objectAsString } };

Then use these string representations in your system prompt.

 
Step 13: Create a Specialized Helper Node
 

For recurring interpolation patterns, create a dedicated helper Function node:

// Prompt Formatter Function
function formatPrompt(template, variables) {
  let result = template;
  for (const [key, value] of Object.entries(variables)) {
    result = result.replace(new RegExp(`{{${key}}}`, 'g'), value);
  }
  return result;
}

const template = "Your name is {{name}} and your task is {{task}}";
const variables = {
  name: $node["Input"].json["name"],
  task: $node["Input"].json["task"]
};

const formattedPrompt = formatPrompt(template, variables);
return { json: { formattedPrompt } };

This approach gives you more control over the interpolation process.

 
Step 14: Submit a Bug Report if Needed
 

If you've tried all the above steps and the issue persists, it might be a bug in n8n. Consider submitting a detailed bug report:

• Go to the n8n GitHub repository
• Create a new issue with the "Bug" template
• Provide detailed information about your setup and the interpolation issue
• Include a minimal workflow example that reproduces the issue

The n8n team is usually responsive to bug reports, especially those that include clear reproduction steps.

 
Step 15: Apply Your Fix and Test Thoroughly
 

After implementing your chosen solution:

• Test with various types of input data (strings, numbers, objects, arrays)
• Test with edge cases (empty values, very long values, special characters)
• Ensure the system prompts render correctly in all scenarios
• Document your solution for future reference

Thorough testing will ensure that your fix is robust and works across different use cases.