langchain-ai/deepagents · error · TypeError

Namespace component at index {i} must be a string, got {type

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.

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)

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 tuple must not be empty.
• Namespace component at index {i} must not be empty.
• interpreter_ptc must be False, 'safe', 'all', or a list of t
• max_retries must be an int, got {type(max_retries).__name__}
• stream_output_is_visible must be a bool, got {type(stream_ou

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