{"record":{"id":"624b825ba7246d26","repo":"langchain-ai/deepagents","slug":"namespace-component-at-index-i-must-be-a-string","errorCode":null,"errorMessage":"Namespace component at index {i} must be a string, got {type(component).__name__}.","messagePattern":"Namespace component at index (.+?) must be a string, got (.+?)\\.","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"libs/deepagents/deepagents/backends/store.py","lineNumber":76,"sourceCode":"\n    Args:\n        namespace: The namespace tuple to validate.\n\n    Returns:\n        The validated namespace tuple (unchanged).\n\n    Raises:\n        ValueError: If the namespace is empty, contains non-string elements,\n            empty strings, or strings with disallowed characters.\n    \"\"\"\n    if not namespace:\n        msg = \"Namespace tuple must not be empty.\"\n        raise ValueError(msg)\n\n    for i, component in enumerate(namespace):\n        if not isinstance(component, str):\n            msg = f\"Namespace component at index {i} must be a string, got {type(component).__name__}.\"\n            raise TypeError(msg)\n        if not component:\n            msg = f\"Namespace component at index {i} must not be empty.\"\n            raise ValueError(msg)\n        if not _NAMESPACE_COMPONENT_RE.match(component):\n            msg = (\n                f\"Namespace component at index {i} contains disallowed characters: {component!r}. \"\n                f\"Only alphanumeric characters, hyphens, underscores, dots, @, +, colons, and tildes are allowed.\"\n            )\n            raise ValueError(msg)\n\n    return namespace\n\n\nclass StoreBackend(BackendProtocol):\n    \"\"\"Backend that stores files in LangGraph's BaseStore (persistent).\n\n    Uses LangGraph's Store for persistent, cross-conversation storage.\n    Files are organized via namespaces and persist across all threads.","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/deepagents/deepagents/backends/store.py#L58-L94","documentation":"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.","triggerScenarios":"`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.","commonSituations":"Using database integer IDs as namespace segments; forgetting `str(user_id)` after refactoring ID types; deserialized config (JSON numbers) feeding the namespace tuple.","solutions":["Convert components to strings: `namespace=tuple(str(c) for c in components)`","Validate types at the boundary (see the `isinstance(c, str)` guard) before constructing the backend","Use canonical string identifiers (UUID hex, slug) instead of raw numeric IDs","Add a factory function that normalizes and validates the namespace in one place"],"exampleFix":"// before\nbackend = StoreBackend(store, namespace=('files', user_id))  # user_id is int\n\n// after\ncomponents = ('files', user_id)\nassert all(isinstance(c, str) for c in components), 'namespace components must be strings'\nbackend = StoreBackend(store, namespace=tuple(str(c) for c in components))","handlingStrategy":"type-guard","validationCode":"def stringify_namespace(components) -> tuple[str, ...]:\n    ns = tuple(str(c) for c in components)\n    assert all(ns), 'namespace components must be non-empty strings'\n    return ns","typeGuard":"def is_string_namespace(ns) -> bool:\n    return isinstance(ns, tuple) and all(isinstance(c, str) for c in ns)","tryCatchPattern":"try:\n    backend = StoreBackend(store, namespace=raw_components)\nexcept TypeError as e:\n    backend = StoreBackend(store, namespace=tuple(str(c) for c in raw_components))","preventionTips":["Coerce IDs to str (str(user_id), uuid.hex) at the point of namespace construction","Keep namespace values as strings end-to-end; avoid mixing numeric IDs","Type-hint namespace parameters as tuple[str, ...] so type checkers catch violations"],"tags":["python","validation","type-error","store-backend","namespace"],"backgroundTag":"invalid-namespace-type","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}