langchain-ai/langchain · error · ValueError

ref paths are expected to be URI fragments, meaning they sho

Error message

ref paths are expected to be URI fragments, meaning they should start with #.

What it means

Error "ref paths are expected to be URI fragments, meaning they should start with #." thrown in langchain-ai/langchain.

Source

Thrown at libs/core/langchain_core/utils/json_schema.py:35

    Args:
        path: Reference path starting with `'#'` (e.g., `'#/definitions/MyType'`).
        schema: The JSON schema dictionary to search in.

    Returns:
        A deep copy of the referenced object (dict or list).

    Raises:
        ValueError: If the path does not start with `'#'`.
        KeyError: If the reference path is not found in the schema.
    """
    components = path.split("/")
    if components[0] != "#":
        msg = (
            "ref paths are expected to be URI fragments, meaning they should start "
            "with #."
        )
        raise ValueError(msg)
    out: list[Any] | dict[Any, Any] = schema
    for component in components[1:]:
        if component in out:
            if isinstance(out, list):
                msg = f"Reference '{path}' not found."
                raise KeyError(msg)
            out = out[component]
        elif component.isdigit():
            index = int(component)
            if (isinstance(out, list) and 0 <= index < len(out)) or (
                isinstance(out, dict) and index in out
            ):
                out = out[index]
            else:
                msg = f"Reference '{path}' not found."
                raise KeyError(msg)
        else:
            msg = f"Reference '{path}' not found."

View on GitHub (pinned to e32fa9a52e)

Solutions

1. Use URI fragment references that start with '#', e.g. '#/definitions/MyModel'.
2. If you need external file references, resolve them before dereferencing; only local fragments are supported.

Example fix

{'$ref': '#/definitions/MyModel'}

When it happens

Trigger: Raised when dereferencing a JSON Schema $ref whose value is not a URI fragment starting with '#' (e.g. an external URL reference).

Common situations: See trigger scenarios.

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