`get_template_variables` Incorrectly Parses Nested Variables in mustache Format

[Alioth99]

Checked other resources

• I added a very descriptive title to this issue.
• I used the GitHub search to find a similar question and didn't find it.
• I am sure that this is a bug in LangChain rather than my code.
• The bug is not resolved by updating to the latest stable version of LangChain (or the specific integration package).
• I posted a self-contained, minimal, reproducible example. A maintainer can copy it and run it AS IS.

Example Code

from langchain_core.prompts import get_template_variables

# Template with nested variables using mustache syntax
template = "Hello {{user.name}}, your role is {{user.role}}"
template_format = "mustache"

result = get_template_variables(template, template_format)

print(result) # Expected ['user.name', 'user.role'] but got ['user']

Error Message and Stack Trace (if applicable)

No response

Description

The documentation for get_template_variables (see documentation) explicitly states that it only supports "f-string" or "jinja2" formats. However, the function actually supports "mustache" format (as shown in the source code), and it does not raise a ValueError for "unsupported" template formats like "mustache" as the documentation claims it should.

More importantly, get_template_variables has an issue with its "mustache" support: it cannot correctly handle nested variables within the mustache format. For instance, given the template "Hello {{user.name}}, your role is {{user.role}}", when template_format="mustache" is provided, the function is expected to return ['user.name', 'user.role']. Instead, the actual result is ['user']. This shows that the function incorrectly identifies nested variables by truncating them to their top-level component and fails to extract the full, dot-separated variable names.

System Info

System Information

OS: Linux
OS Version: #148-Ubuntu SMP Fri Mar 14 19:05:48 UTC 2025
Python Version: 3.10.16 (main, Dec 11 2024, 16:24:50) [GCC 11.2.0]

Package Information

langchain_core: 0.3.65
langchain: 0.3.25
langchain_community: 0.3.25
langsmith: 0.3.45
langchain_anthropic: 0.3.1
langchain_aws: 0.2.2
langchain_chroma: 0.2.0
langchain_cohere: 0.3.5
langchain_experimental: 0.3.2
langchain_fireworks: 0.2.6
langchain_google_vertexai: 2.0.5
langchain_groq: 0.2.2
langchain_mistralai: 0.2.4
langchain_openai: 0.2.14
langchain_text_splitters: 0.3.8
langchain_together: 0.2.0
langchain_unstructured: 0.1.5
langgraph_sdk: 0.1.34

Optional packages not installed

langserve

Other Dependencies

aiohttp: 3.12.12
aiohttp<4.0.0,>=3.8.3: Installed. No version info available.
anthropic: 0.40.0
anthropic[vertexai]: Installed. No version info available.
async-timeout<5.0.0,>=4.0.0;: Installed. No version info available.
boto3: 1.35.42
chromadb: 0.5.23
cohere: 5.15.0
dataclasses-json<0.7,>=0.5.7: Installed. No version info available.
defusedxml: 0.7.1
fastapi: 0.115.9
fireworks-ai: 0.15.7
google-cloud-aiplatform: 1.70.0
google-cloud-storage: 2.18.2
groq: 0.11.0
httpx: 0.28.1
httpx-sse: 0.4.0
httpx-sse<1.0.0,>=0.4.0: Installed. No version info available.
jsonpatch<2.0,>=1.33: Installed. No version info available.
langchain-anthropic;: Installed. No version info available.
langchain-aws;: Installed. No version info available.
langchain-azure-ai;: Installed. No version info available.
langchain-cohere;: Installed. No version info available.
langchain-community;: Installed. No version info available.
langchain-core<1.0.0,>=0.3.51: Installed. No version info available.
langchain-core<1.0.0,>=0.3.58: Installed. No version info available.
langchain-core<1.0.0,>=0.3.65: Installed. No version info available.
langchain-deepseek;: Installed. No version info available.
langchain-fireworks;: Installed. No version info available.
langchain-google-genai;: Installed. No version info available.
langchain-google-vertexai;: Installed. No version info available.
langchain-groq;: Installed. No version info available.
langchain-huggingface;: Installed. No version info available.
langchain-mistralai;: Installed. No version info available.
langchain-ollama;: Installed. No version info available.
langchain-openai;: Installed. No version info available.
langchain-perplexity;: Installed. No version info available.
langchain-text-splitters<1.0.0,>=0.3.8: Installed. No version info available.
langchain-together;: Installed. No version info available.
langchain-xai;: Installed. No version info available.
langchain<1.0.0,>=0.3.25: Installed. No version info available.
langsmith-pyo3: Installed. No version info available.
langsmith<0.4,>=0.1.125: Installed. No version info available.
langsmith<0.4,>=0.1.17: Installed. No version info available.
langsmith<0.4,>=0.3.45: Installed. No version info available.
numpy: 1.26.4
numpy>=1.26.2;: Installed. No version info available.
numpy>=2.1.0;: Installed. No version info available.
openai: 1.86.0
openai-agents: Installed. No version info available.
opentelemetry-api: 1.34.1
opentelemetry-exporter-otlp-proto-http: 1.34.1
opentelemetry-sdk: 1.34.1
orjson: 3.10.16
packaging: 24.1
packaging<25,>=23.2: Installed. No version info available.
pandas: 2.2.3
pydantic: 2.9.2
pydantic-settings<3.0.0,>=2.4.0: Installed. No version info available.
pydantic<3.0.0,>=2.7.4: Installed. No version info available.
pydantic>=2.7.4: Installed. No version info available.
pytest: 8.3.4
PyYAML>=5.3: Installed. No version info available.
requests: 2.32.3
requests-toolbelt: 1.0.0
requests<3,>=2: Installed. No version info available.
rich: 14.0.0
SQLAlchemy<3,>=1.4: Installed. No version info available.
tabulate: 0.9.0
tenacity!=8.4.0,<10,>=8.1.0: Installed. No version info available.
tenacity!=8.4.0,<10.0.0,>=8.1.0: Installed. No version info available.
tiktoken: 0.8.0
tokenizers: 0.21.1
typing-extensions>=4.7: Installed. No version info available.
unstructured-client: 0.25.9
unstructured[all-docs]: Installed. No version info available.
zstandard: 0.23.0

[YantD729]

I am fixing it here: #31991

[YantD729]

Well...I initially implemented a fix that makes get_template_variables return full dot-separated variable names (e.g., user.name, user.role) for Mustache templates.

However, upon deeper inspection, this behavior causes breaking changes in parts of LangChain that rely on structured input validation, such as StructuredPrompt, which expects nested variables to be passed as top-level objects (e.g., {"user": {"name": "foo"}}) rather than dot-separated flat keys.

Since Mustache is designed to work with structured input objects (not flattened dot strings), the original behavior of returning just the top-level variable (e.g., user) aligns more closely with Mustache semantics.

I’m now considering closing or revising this PR to respect Mustache’s structure-driven design, and possibly add documentation or warnings instead of altering variable detection behavior in ways that break existing use cases.

[eyurtsev]

We can update the doc-string to explain semantics. This does not appear like an issue based on the report so far

[eyurtsev]

If someone wants to improve the doc-strings to explain the behavior and practice good technical writing, we'd consider a PR for that

[keenborder786]

@eyurtsev okay