langchain-ai/langchain · error · ValueError

Invalid examples format. Only list or string are supported.

Error message

Invalid examples format. Only list or string are supported.

What it means

`_load_examples` accepts `examples` in exactly two shapes: a list (inline examples) or a string (path to a `.json`/`.yaml` file). Anything else — a dict, number, None, nested object — raises this `ValueError`, since the loader has no way to interpret it as examples.

Source

Thrown at libs/core/langchain_core/prompts/loading.py:138

    """Load examples if necessary."""
    if isinstance(config["examples"], list):
        pass
    elif isinstance(config["examples"], str):
        path = Path(config["examples"])
        if not allow_dangerous_paths:
            _validate_path(path)
        with path.open(encoding="utf-8") as f:
            if path.suffix == ".json":
                examples = json.load(f)
            elif path.suffix in {".yaml", ".yml"}:
                examples = yaml.safe_load(f)
            else:
                msg = "Invalid file format. Only json or yaml formats are supported."
                raise ValueError(msg)
        config["examples"] = examples
    else:
        msg = "Invalid examples format. Only list or string are supported."
        raise ValueError(msg)  # noqa:TRY004
    return config


def _load_output_parser(config: dict[str, Any]) -> dict[str, Any]:
    """Load output parser."""
    if config_ := config.get("output_parser"):
        if output_parser_type := config_.get("_type") != "default":
            msg = f"Unsupported output parser {output_parser_type}"
            raise ValueError(msg)
        config["output_parser"] = StrOutputParser(**config_)
    return config


def _load_few_shot_prompt(
    config: dict[str, Any], *, allow_dangerous_paths: bool = False
) -> FewShotPromptTemplate:
    """Load the "few shot" prompt from the config."""
    # Load the suffix and prefix templates.

View on GitHub (pinned to e32fa9a52e)

Solutions

1. Wrap the value in a list: `"examples": [{ ... }]`.
2. Remove the `examples` key entirely if you mean to have zero examples (and expect a `KeyError` — prefer an empty list `[]` which passes).
3. If examples live in a file, use the string path form with a `.json`/`.yaml` suffix.

Example fix

# before
# examples.yaml content loaded into config as:
# {"examples": {"q": "hi", "a": "hello"}}

# after
# {"examples": [{"q": "hi", "a": "hello"}]}

ex = config.get('examples')
if not isinstance(ex, (list, str)):
    raise ValueError('examples must be a list or a file-path string')
load_prompt_from_config(config)

def is_valid_examples(examples: object) -> bool:
    return isinstance(examples, (list, str))

When it happens

Trigger: A few-shot config with `"examples": {"0": {...}}` (dict), `"examples": null`, or `"examples": 5`. Note a missing `examples` key raises `KeyError` earlier at `config["examples"]`; this error is for a present-but-wrong-typed value.

Common situations: YAML configs where a single example collapses into a dict instead of a one-element list; JSON `null` for optional examples; feeding an `example_selector` config dict where examples were expected.

Related errors

• Only one of example_prompt and example_prompt_path should be
• Both `{var_name}_path` and `{var_name}` cannot be provided.
• Loading {config_type} prompt not supported
• Unsupported template file format: '{resolved_path.suffix}'.
• Invalid file format. Only json or yaml formats are supported

AI-assisted analysis of langchain-ai/langchain@e32fa9a52e (2026-08-14). Data as JSON: /api/errors/b23d1b31873ee714. Report an issue: GitHub.