langchain-ai/deepagents · error · ValueError

Namespace tuple must not be empty.

Error message

Namespace tuple must not be empty.

What it means

`StoreBackend._validate_namespace` requires a non-empty namespace tuple identifying where files live in the LangGraph store. An empty tuple has no scope to read or write under, so a `ValueError` is raised immediately. This validation runs before any store access, including from `_get_namespace`.

Source

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

    alphanumeric (a-z, A-Z, 0-9), hyphen (-), underscore (_), dot (.),
    at sign (@), plus (+), colon (:), and tilde (~).

    Characters like `*`, `?`, `[`, `]`, `{`, `}`, etc. are
    rejected to prevent wildcard or glob injection in store lookups.

    Args:
        namespace: The namespace tuple to validate.

    Returns:
        The validated namespace tuple (unchanged).

    Raises:
        ValueError: If the namespace is empty, contains non-string elements,
            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

View on GitHub (pinned to a1af029e6e)

Solutions

1. Pass a non-empty namespace, e.g. `StoreBackend(store, namespace=('files', user_id))`
2. Validate/derive the namespace before constructing the backend and fail fast with a clearer app-level error
3. Check for empty/None config values that feed the namespace and substitute defaults
4. Add a unit test asserting the namespace is non-empty in your backend factory

Example fix

// before
backend = StoreBackend(store, namespace=())

// after
ns = tuple(x for x in ('files', user_id) if x)
if not ns:
    raise ValueError('user_id is required to build the store namespace')
backend = StoreBackend(store, namespace=ns)

def valid_namespace(ns) -> bool:
    return isinstance(ns, tuple) and len(ns) > 0 and all(isinstance(c, str) for c in ns)

def is_nonempty_str_tuple(ns) -> bool:
    return isinstance(ns, tuple) and len(ns) > 0 and all(isinstance(c, str) for c in ns)

try:
    backend = StoreBackend(store, namespace=ns)
except (ValueError, TypeError) as e:
    raise ValueError(f'bad store namespace {ns!r}: {e}') from e

When it happens

Trigger: Constructing a `StoreBackend` with `namespace=()` or calling `_get_namespace`/`_validate_namespace(())`; deriving an empty namespace from kwargs/defaults when a required namespace component was omitted.

Common situations: Building the namespace programmatically (e.g. filtering out a user/org prefix) so all components disappear; copy-pasting store setup examples without filling in tuple elements; config values that resolve to empty and collapse the tuple.

Related errors

• Namespace component at index {i} must not be empty.
• Namespace component at index {i} must be a string, got {type
• max_retries must be >= 0
• RubricMiddleware: `max_iterations` must be positive, got {ma
• RubricMiddleware: `grader_state_schema` is required with `bu

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