Variable Resolution and Template Substitution#

Variable resolution in Dify workflows revolves around the VariablePool (from the external graphon package, v0.6.0), which acts as the single shared store for all runtime variable values. Every node reads and writes through this pool, and references between nodes use the {{#node_id.variable_name#}} template syntax.

Key source files:

• api/core/workflow/variable_pool_initializer.py — add_variables_to_pool() and add_node_inputs_to_pool() helpers
• api/core/workflow/system_variables.py — SystemVariableKey enum, build_bootstrap_variables(), and build_system_variables()
• api/core/workflow/node_factory.py — wires each node type to its dependencies, including the variable pool
• graphon.runtime.VariablePool (external) — core add(), get(), convert_template(), and convert_template_escape() methods
• api/tests/unit_tests/core/workflow/nodes/http_request/test_http_request_executor.py — authoritative tests for HTTP node template behavior

Template Syntax#

The placeholder format is {{#<node_id>.<variable_name>#}}. Internally, the template engine parses this with a regex that accepts only alphanumeric characters and underscores in node IDs:

\{\{#([a-zA-Z0-9_]{1,50}(?:\.[a-zA-Z_][a-zA-Z0-9_]{0,29}){1,10})#\}\}

Critical caveat: Node IDs containing hyphens (e.g., {{#node-1.text#}}) silently fail to match this pattern. The placeholder is left as-is in the output rather than raising an error.

Variables are stored and retrieved using selector tuples: (node_id, variable_name). For example, variable_pool.add(["pre_node_id", "number"], 42) stores 42 under the selector ("pre_node_id", "number"), which is then resolved when a template containing {{#pre_node_id.number#}} is processed 1.

convert_template() returns an object with three output properties:

• .text — plain text rendering
• .log — log-friendly rendering (used for model input logging)
• .markdown — markdown rendering (used for Human Input form content)

VariablePool Lifecycle#

The pool is bootstrapped once at workflow start and then mutated in-place as each node executes.

Bootstrap phase — build_bootstrap_variables() 2 assembles initial variables from four namespaces, each keyed by a dedicated sentinel node ID:

User inputs (from the START node) are then written via add_node_inputs_to_pool(), which stores each input under the root node ID and any compatible aliases.

Execution phase — The pool instance lives in GraphRuntimeState and is shared across all nodes 4. As each node completes, it writes its outputs back with variable_pool.add((node_id, key), value). Downstream nodes resolve those values when their own templates are processed.

Certain LLM-compatible nodes (LLM, QUESTION_CLASSIFIER, PARAMETER_EXTRACTOR) that use memory require CONVERSATION_ID to be available at construction time. get_node_creation_preload_selectors() 5 handles pre-loading those selectors before DifyNodeFactory.create_node() runs.

Template Substitution Across Node Types#

DifyNodeFactory.create_node() 6 wires each node type to the dependencies it needs for template resolution. All nodes receive graph_runtime_state (containing the pool), but higher-level rendering helpers vary:

HTTP Request Node: JSON Body Escaping#

The HTTP Request Executor resolves templates in URLs, headers, params, and body fields. Body type handling differs:

• form-data / x-www-form-urlencoded: convert_template() is called; substituted values become strings 13.
• json: Uses convert_template_escape(), which additionally escapes " → \" and \n → \\n in string values before calling json.loads(). Non-string (numeric, object) segments are left unescaped 14. This prevents JSON parse failures when LLM outputs or user text contain line breaks or quotes.

Type-aware substitution in JSON bodies 15:

• Numbers remain unquoted: {"count": {{#node.count#}}} → {"count": 42}
• Strings that appear unquoted in the template are auto-quoted via json_repair
• Objects/dicts expand inline

The json_repair library (v0.60.1) is used as a fallback to fix structurally broken JSON that results from substitution. It also handles the edge case where UUID strings substituted without quotes would be truncated by naïve repair logic — see the UUID test case.

Common Failure Modes#

LLM node receives model config instead of template output 16
Symptom: the upstream Template node renders correctly, but the LLM receives the node's model config object instead of the template output. This points to the VariablePool not containing the upstream node's output when the LLM runs — check that the Template node is truly upstream (connected by an edge) and that no parallel-branch issue causes the LLM to be instantiated before the Template node writes its output.

Human Intervention node shows raw {{#...#}} after page refresh 17
Symptom: after a page refresh during a pending HITL pause, the form shows the raw placeholder like {{#1778488854176.text#}} instead of the resolved value. Root cause is likely one of: (a) render_form_content_before_submission() failed to call convert_template() at pause time (VariablePool not yet populated), or (b) the API response returns the raw form_content field instead of rendered_content. The frontend does not resolve variables client-side and depends entirely on the pre-rendered value from the backend.

Variable Not Found on branch convergence 18
Symptom: when a conditional branch is skipped, its output variables are undefined. Downstream nodes that reference those variables throw a "Variable Not Found" error and freeze the workflow. The pre-rendering validation checks variable availability before Jinja2 evaluates. Workaround: use a Variable Aggregator node per variable — it silently ignores skipped branches and always provides a resolved output variable.

Silent substitution failure for hyphenated node IDs
The {{#...#}} regex only allows [a-zA-Z0-9_] in the node ID segment. References to nodes with hyphens in their IDs (e.g., {{#my-node.output#}}) will not be substituted and will pass through as raw text with no error raised.