run-llama/llama_index · error · ImportError

You need to install jsonpath-ng to use this function!

Error message

You need to install jsonpath-ng to use this function!

What it means

default_output_processor in json_query.py parses the LLM's JSONPath output with jsonpath_ng. llama-index-core does not depend on jsonpath-ng, so the import inside the function fails with an ImportError pointing you at the missing optional package.

Source

Thrown at llama-index-core/llama_index/core/indices/struct_store/json_query.py:72

        return llm_output

    return llm_output_parsed


def default_output_processor(llm_output: str, json_value: JSONType) -> Dict[str, str]:
    """Default output processor that extracts values based on JSON Path expressions."""
    # Post-process the LLM output to remove the JSONPath: prefix
    llm_output = llm_output.replace("JSONPath: ", "").replace("JSON Path: ", "").strip()

    # Split the given string into separate JSON Path expressions
    expressions = [expr.strip() for expr in llm_output.split(",")]

    try:
        from jsonpath_ng.ext import parse  # pants: no-infer-dep
        from jsonpath_ng.jsonpath import DatumInContext  # pants: no-infer-dep
    except ImportError as exc:
        IMPORT_ERROR_MSG = "You need to install jsonpath-ng to use this function!"
        raise ImportError(IMPORT_ERROR_MSG) from exc

    results: Dict[str, str] = {}

    for expression in expressions:
        try:
            datum: List[DatumInContext] = parse(expression).find(json_value)
            if datum:
                key = expression.split(".")[
                    -1
                ]  # Extracting "title" from "$.title", for example
                results[key] = ", ".join(str(i.value) for i in datum)
        except Exception as exc:
            raise ValueError(f"Invalid JSON Path: {expression}") from exc

    return results


class JSONQueryEngine(BaseQueryEngine):

View on GitHub (pinned to afd0fef371)

Solutions

1. pip install jsonpath-ng
2. Add jsonpath-ng to your project's dependency list
3. If you cannot install it, supply a custom output_parser to the query engine that extracts values without JSONPath

Example fix

# before
query_engine = JSONQueryEngine(json_value=data, sql_table_name='...')
await query_engine.aquery('...')  # ImportError at query time

# after
pip install jsonpath-ng
# (code unchanged)

try:
    import jsonpath_ng  # noqa: F401
    HAS_JSONPATH = True
except ImportError:
    HAS_JSONPATH = False

if not HAS_JSONPATH:
    raise RuntimeError('JSONQueryEngine requires jsonpath-ng: pip install jsonpath-ng')

def has_jsonpath() -> bool:
    try:
        import jsonpath_ng  # noqa: F401
        return True
    except ImportError:
        return False

try:
    result = query_engine.query(q)
except ImportError as e:
    if 'jsonpath-ng' in str(e):
        raise RuntimeError('install jsonpath-ng or pass a custom output_parser') from e
    raise

When it happens

Trigger: Using JSONQueryEngine (GPTJSONQueryEngine / legacy JSON query engine) with its default output processor; the import of jsonpath_ng.ext is attempted only when a query runs, so construction succeeds and the first query fails.

Common situations: Minimal llama-index installs; CI images without optional deps; upgrading environments where jsonpath-ng was previously installed transitively but no longer is.

Related errors

• Invalid JSON Path: {expression}
• Please install scikit-learn to use this feature.
• Malformed partial JSON encountered.
• Failed to parse pydantic object from guidance program. Proba
• Failed to serialize additional_kwargs value: {value}

AI-assisted analysis of run-llama/llama_index@afd0fef371 (2026-08-15). Data as JSON: /api/errors/2c7280beb411aaa6. Report an issue: GitHub.