langchain-ai/deepagents · error · ValueError

Namespace component at index {i} must not be empty.

Error message

Namespace component at index {i} must not be empty.

What it means

Within a namespace tuple, no component may be an empty string: `_validate_namespace` raises `ValueError` for `''` elements, since empty segments would create ambiguous or colliding store keys. The check runs after the type check and before the allowed-characters regex check.

Source

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

    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


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).

View on GitHub (pinned to a1af029e6e)

Solutions

1. Filter out empty strings before constructing: `ns = tuple(c for c in raw if c)`
2. Replace optional empty segments with meaningful placeholders (e.g. 'default', '_')
3. Validate config-derived inputs upstream and reject empty values with a clear message
4. Centralize namespace construction in one helper that applies `str()`, emptiness, and regex checks

Example fix

// before
ns = tuple(base.split('/'))  # may contain ''
backend = StoreBackend(store, namespace=ns)

// after
ns = tuple(seg for seg in base.split('/') if seg)
if not ns:
    raise ValueError('namespace resolved to nothing')
backend = StoreBackend(store, namespace=ns)

def clean_namespace(raw: str | list[str]) -> tuple[str, ...]:
    parts = [p for p in (raw.split('/') if isinstance(raw, str) else raw) if p]
    if not parts:
        raise ValueError('namespace must contain at least one non-empty component')
    return tuple(parts)

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

try:
    backend = StoreBackend(store, namespace=ns)
except ValueError as e:
    ns = tuple(c for c in ns if c)
    backend = StoreBackend(store, namespace=ns)

When it happens

Trigger: `StoreBackend(store, namespace=('files', ''))`; joining/joining-splitting strings into components where an empty segment slips in (e.g. `''.split('/')` or filtering that keeps empty strings); optional middle segments left as empty strings instead of being dropped.

Common situations: Building namespaces from URL/config paths that contain empty segments; template-based namespace construction with unfilled placeholders; over-aggressive string splitting that yields `''` between delimiters.

Related errors

• Namespace tuple 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/4e617e6ee3d27636. Report an issue: GitHub.