langchain-ai/deepagents · error · TypeError

Namespace component at index

Error message

Namespace component at index {i} must be a string, got {type(component).__name__}.

What it means

Namespace components in `StoreBackend` must be strings; `_validate_namespace` raises a `TypeError` when an element is not a `str`, reporting the offending index and actual type. This guards against passing ints, enums, or Path objects where string namespace segments are required by the store API.

Solutions

1. Convert components to strings: `namespace=tuple(str(c) for c in components)`
2. Validate types at the boundary (see the `isinstance(c, str)` guard) before constructing the backend
3. Use canonical string identifiers (UUID hex, slug) instead of raw numeric IDs
4. Add a factory function that normalizes and validates the namespace in one place

Example fix

// before
backend = StoreBackend(store, namespace=('files', user_id))  # user_id is int

// after
components = ('files', user_id)
assert all(isinstance(c, str) for c in components), 'namespace components must be strings'
backend = StoreBackend(store, namespace=tuple(str(c) for c in components))

def stringify_namespace(components) -> tuple[str, ...]:
    ns = tuple(str(c) for c in components)
    assert all(ns), 'namespace components must be non-empty strings'
    return ns

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

try:
    backend = StoreBackend(store, namespace=raw_components)
except TypeError as e:
    backend = StoreBackend(store, namespace=tuple(str(c) for c in raw_components))

When it happens

Trigger: `StoreBackend(store, namespace=('files', 42))` or a Path/UUID/enum object passed as a component; programmatically assembled namespaces mixing typed values (user IDs as ints) with strings.

Common situations: Using database integer IDs as namespace segments; forgetting `str(user_id)` after refactoring ID types; deserialized config (JSON numbers) feeding the namespace tuple.

Related errors

• Namespace component at index
• Namespace tuple must not be empty.
• context.auto_approve must be a boolean or null, got
• context.hooks_server_events must be a list of strings or…
• context. must be a string or null, got .

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

Appendix: source

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

    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


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.

View on GitHub (pinned to a1af029e6e)