{"record":{"id":"a9740b752f0068de","repo":"langchain-ai/deepagents","slug":"namespace-tuple-must-not-be-empty","errorCode":null,"errorMessage":"Namespace tuple must not be empty.","messagePattern":"Namespace tuple must not be empty\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"libs/deepagents/deepagents/backends/store.py","lineNumber":71,"sourceCode":"    alphanumeric (a-z, A-Z, 0-9), hyphen (-), underscore (_), dot (.),\n    at sign (@), plus (+), colon (:), and tilde (~).\n\n    Characters like `*`, `?`, `[`, `]`, `{`, `}`, etc. are\n    rejected to prevent wildcard or glob injection in store lookups.\n\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","sourceCodeStart":53,"sourceCodeEnd":89,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/deepagents/deepagents/backends/store.py#L53-L89","documentation":"`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`.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pass a non-empty namespace, e.g. `StoreBackend(store, namespace=('files', user_id))`","Validate/derive the namespace before constructing the backend and fail fast with a clearer app-level error","Check for empty/None config values that feed the namespace and substitute defaults","Add a unit test asserting the namespace is non-empty in your backend factory"],"exampleFix":"// before\nbackend = StoreBackend(store, namespace=())\n\n// after\nns = tuple(x for x in ('files', user_id) if x)\nif not ns:\n    raise ValueError('user_id is required to build the store namespace')\nbackend = StoreBackend(store, namespace=ns)","handlingStrategy":"validation","validationCode":"def valid_namespace(ns) -> bool:\n    return isinstance(ns, tuple) and len(ns) > 0 and all(isinstance(c, str) for c in ns)","typeGuard":"def is_nonempty_str_tuple(ns) -> bool:\n    return isinstance(ns, tuple) and len(ns) > 0 and all(isinstance(c, str) for c in ns)","tryCatchPattern":"try:\n    backend = StoreBackend(store, namespace=ns)\nexcept (ValueError, TypeError) as e:\n    raise ValueError(f'bad store namespace {ns!r}: {e}') from e","preventionTips":["Always construct namespaces through a single validated helper","Never build namespaces from values that can be None/empty without filtering","Add unit tests for namespace construction covering empty and missing components"],"tags":["python","validation","store-backend","namespace","value-error"],"backgroundTag":"invalid-namespace","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}