langchain-ai/langgraph · error · ValueError

Invalid filter key: ' '. Filter keys must contain only…

Error message

Invalid filter key: '{key}'. Filter keys must contain only alphanumeric characters, underscores, dots, and hyphens.

What it means

A SQL-injection guard in _validate_filter_key: metadata filter keys are interpolated into SQL strings (they cannot be parameterized), so each key is checked against the regex ^[a-zA-Z0-9_.-]+$. The error fires when a search filter dict contains a key with characters outside alphanumerics, underscores, dots, and hyphens (spaces, quotes, parentheses, etc.).

Solutions

1. Use only alphanumeric, underscore, dot, and hyphen characters in filter keys, e.g. {'user_id': '42'} instead of {'user id': '42'}
2. Flatten nested filters into dotted JSON paths like 'attributes.source'
3. Avoid special characters or spaces when designing the metadata keys you will filter on

When it happens

Trigger: Thrown at libs/checkpoint-sqlite/langgraph/checkpoint/sqlite/utils.py:26 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of langchain-ai/langgraph@38031739e5 (2026-08-26). Data as JSON: /api/errors/06572e8693c7d43a. Report an issue: GitHub.

Appendix: source

Thrown at libs/checkpoint-sqlite/langgraph/checkpoint/sqlite/utils.py:26

from langchain_core.runnables import RunnableConfig
from langgraph.checkpoint.base import get_checkpoint_id

_FILTER_PATTERN = re.compile(r"^[a-zA-Z0-9_.-]+$")


def _validate_filter_key(key: str) -> None:
    """Validate that a filter key is safe for use in SQL queries.

    Args:
        key: The filter key to validate

    Raises:
        ValueError: If the key contains invalid characters that could enable SQL injection
    """
    # Allow alphanumeric characters, underscores, dots, and hyphens
    # This covers typical JSON property names while preventing SQL injection
    if not _FILTER_PATTERN.match(key):
        raise ValueError(
            f"Invalid filter key: '{key}'. Filter keys must contain only alphanumeric characters, underscores, dots, and hyphens."
        )


def _metadata_predicate(
    metadata_filter: dict[str, Any],
) -> tuple[Sequence[str], Sequence[Any]]:
    """Return WHERE clause predicates for (a)search() given metadata filter.

    This method returns a tuple of a string and a tuple of values. The string
    is the parametered WHERE clause predicate (excluding the WHERE keyword):
    "column1 = ? AND column2 IS ?". The tuple of values contains the values
    for each of the corresponding parameters.
    """

    def _where_value(query_value: Any) -> tuple[str, Any]:
        """Return tuple of operator and value for WHERE clause predicate."""
        if query_value is None:

View on GitHub (pinned to 38031739e5)