langchain-ai/langgraph · error · ValueError

Invalid filter key: '{key}'. Filter keys must contain only a

Error message

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

What it means

Error "Invalid filter key: '{key}'. Filter keys must contain only alphanumeric characters, underscores, dots, and hyphens." thrown in langchain-ai/langgraph.

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)

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.