langchain-ai/langgraph · error · InvalidNamespaceError

Invalid namespace label

Error message

Invalid namespace label '{label}' found in {namespace}. Namespace labels cannot contain periods ('.').

What it means

Content check inside _validate_namespace: a label within the namespace contains a '.' character. Dots are the namespace separator in wire/storage representations (e.g. 'docs.user1'), so embedding one inside a label would make the path ambiguous and enable namespace-collision attacks; the offending label and full namespace are shown.

Solutions

  1. Replace '.' in labels with another delimiter such as '-' or '_' (e.g. 'v1.2' -> 'v1-2')
  2. Split pre-joined namespaced strings into real tuples: ('docs', 'user1') instead of ('docs.user1',)
  3. Sanitize external identifiers before using them as namespace labels
Defensive patterns

Strategy: validation

When it happens

Trigger: Thrown at libs/checkpoint/langgraph/checkpoint/store/base/__init__.py:1273 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/19a4c84eddf41e3e. Report an issue: GitHub.

Appendix: source

Thrown at libs/checkpoint/langgraph/checkpoint/store/base/__init__.py:1273

        if "." in label:
            raise InvalidNamespaceError(
                f"Invalid namespace label '{label}' found in {namespace}. Namespace labels cannot contain periods ('.')."
            )
        elif not label:
            raise InvalidNamespaceError(
                f"Namespace labels cannot be empty strings. Got {label} in {namespace}"
            )
    if namespace[0] == "langgraph":
        raise InvalidNamespaceError(
            f'Root label for namespace cannot be "langgraph". Got: {namespace}'
        )

View on GitHub (pinned to 38031739e5)