langchain-ai/langgraph · error · ValueError

Invalid namespace label

Error message

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

What it means

Client-side namespace guard in the async store put_item: each label in the namespace tuple is checked for '.', which is reserved as the namespace separator in the LangGraph Store API. A dotted label would be ambiguous when the namespace is serialized/joined, so it is rejected up front.

Solutions

1. Split dotted labels into separate tuple elements: ("my.namespace",) -> ("my", "namespace")
2. Replace '.' with '_' or another separator in the label

When it happens

Trigger: Thrown at libs/sdk-py/langgraph_sdk/_async/store.py:73 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/26a82629a0bf2294. Report an issue: GitHub.

Appendix: source

Thrown at libs/sdk-py/langgraph_sdk/_async/store.py:73

            params: Optional query parameters to include with the request.

        Returns:
            `None`

        ???+ example "Example Usage"

            ```python
            client = get_client(url="http://localhost:2024")
            await client.store.put_item(
                ["documents", "user123"],
                key="item456",
                value={"title": "My Document", "content": "Hello World"}
            )
            ```
        """
        for label in namespace:
            if "." in label:
                raise ValueError(
                    f"Invalid namespace label '{label}'. Namespace labels cannot contain periods ('.')."
                )
        payload = {
            "namespace": namespace,
            "key": key,
            "value": value,
            "index": index,
            "ttl": ttl,
        }
        await self.http.put(
            "/store/items", json=_provided_vals(payload), headers=headers, params=params
        )

    async def get_item(
        self,
        namespace: Sequence[str],
        /,
        key: str,

View on GitHub (pinned to 38031739e5)