langchain-ai/deepagents · error · ValueError

Namespace component at index {i} contains disallowed charact

Error message

Namespace component at index {i} contains disallowed characters: {component!r}. Only alphanumeric characters, hyphens, underscores, dots, @, +, colons, and tildes are allowed.

What it means

StoreBackend namespaces are tuples of string components that become LangGraph BaseStore namespace prefixes. `_validate_namespace` rejects any component containing characters outside the allowed set (alphanumeric, `-`, `_`, `.`, `@`, `+`, `:`, `~`) so persisted store keys stay unambiguous and portable. A non-string component also fails the regex check and raises this ValueError.

Source

Thrown at libs/deepagents/deepagents/backends/store.py:85

            empty strings, or strings with disallowed characters.
    """
    if not namespace:
        msg = "Namespace tuple must not be empty."
        raise ValueError(msg)

    for i, component in enumerate(namespace):
        if not isinstance(component, str):
            msg = f"Namespace component at index {i} must be a string, got {type(component).__name__}."
            raise TypeError(msg)
        if not component:
            msg = f"Namespace component at index {i} must not be empty."
            raise ValueError(msg)
        if not _NAMESPACE_COMPONENT_RE.match(component):
            msg = (
                f"Namespace component at index {i} contains disallowed characters: {component!r}. "
                f"Only alphanumeric characters, hyphens, underscores, dots, @, +, colons, and tildes are allowed."
            )
            raise ValueError(msg)

    return namespace


class StoreBackend(BackendProtocol):
    """Backend that stores files in LangGraph's BaseStore (persistent).

    Uses LangGraph's Store for persistent, cross-conversation storage.
    Files are organized via namespaces and persist across all threads.

    Files are scoped by the caller-supplied `namespace` factory (e.g. per-user
    or per-assistant isolation).
    """

    def __init__(
        self,
        *,
        namespace: NamespaceFactory,

View on GitHub (pinned to a1af029e6e)

Solutions

Sanitize each namespace component to the allowed character set before constructing the StoreBackend
Coerce non-string values with str() and strip or replace disallowed characters (e.g. replace `/` with `-`)
Split path-like values into separate tuple components instead of embedding `/` in one component
Catch the ValueError to surface a clear configuration error at startup rather than at first store access

Example fix

// before
backend = StoreBackend(store=store, namespace=lambda rt: (f"files/{rt.context['user']}",))
// after
user = str(rt.context['user']).replace('/', '-').replace(' ', '_')
backend = StoreBackend(store=store, namespace=lambda rt: ('files', user))

Defensive patterns

Strategy: validation

Validate before calling

import re
_COMPONENT_RE = re.compile(r'^[A-Za-z0-9._@+:~-]+$')
def valid_namespace(namespace) -> bool:
    return (
        isinstance(namespace, tuple)
        and all(isinstance(c, str) and _COMPONENT_RE.match(c) for c in namespace)
    )
if not valid_namespace(ns):
    raise ValueError(f'invalid namespace: {ns!r}')
backend = StoreBackend(store=store, namespace=ns)

Type guard

def is_valid_namespace(namespace: object) -> bool:
    import re
    return (
        isinstance(namespace, tuple)
        and all(
            isinstance(c, str)
            and re.fullmatch(r'[A-Za-z0-9._@+:~-]+', c) is not None
            for c in namespace
        )
    )

Prevention

Build namespaces from sanitized ids, never raw paths or user input
Keep path-like segments as separate tuple elements instead of embedding '/'
Coerce to str explicitly (str(user_id)) before forming the tuple
Validate namespaces at construction/startup, not at first store access

When it happens

Trigger: Passing a namespace tuple with components containing spaces, slashes, `*`, `?`, non-ASCII characters, or non-string values (e.g. ints, None) either directly to `StoreBackend(store=..., namespace=...)`, via a namespace factory callable, or by constructing a StoreBackend subclass with a bad default namespace.

Common situations: Building a namespace from user input or file paths without sanitizing (`/tmp/x` contains `/`); interpolating ints (`(123,)` instead of `('123',)`); joining namespace parts with `/` instead of keeping them as separate tuple elements.

Related errors

AI-assisted analysis of langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/af5be3f4e6484ea9. Report an issue: GitHub.