RyanCodrai/turbovec · error · ValueError

namespace must not contain path separators ('/' or '\\') or

Error message

namespace must not contain path separators ('/' or '\\') or '..'; got {namespace!r}. It names a store within persist_dir, not a path.

What it means

Raised in _validate_namespace when the namespace contains a path separator ('/', backslash, or os.sep) or '..'. Composed into the persist filename, such a namespace performs path traversal and resolves outside persist_dir; it is rejected loudly rather than silently basename'd, since silent rewriting could load a different store than the caller named.

Source

Thrown at turbovec-python/python/turbovec/llama_index.py:170

    ``persist_dir`` (path traversal), an empty/``.`` namespace names the
    directory itself rather than a store file, and a ``:`` forms a
    Windows drive-relative name (``C:foo``) that escapes ``persist_dir``
    without any separator. We reject these loudly rather than silently
    basenaming them — silent rewriting could load a *different* store
    than the caller named. Any other namespace is accepted verbatim
    (alphanumerics, dash, underscore, dots, and other non-separator
    characters); dotted namespaces such as ``v1.2`` map to distinct
    file pairs and coexist in one ``persist_dir``.

    This is a deliberate divergence from ``SimpleVectorStore``, which does
    not sanitize its namespace, in the safer direction.
    """
    if namespace == "" or namespace == ".":
        raise ValueError(
            f"namespace must be a non-empty name, got {namespace!r}"
        )
    if "/" in namespace or "\\" in namespace or os.sep in namespace or ".." in namespace:
        raise ValueError(
            "namespace must not contain path separators ('/' or '\\\\') or "
            f"'..'; got {namespace!r}. It names a store within persist_dir, "
            "not a path."
        )
    if ":" in namespace:
        raise ValueError(
            "namespace must not contain ':' (a Windows drive-relative name "
            f"like 'C:foo' escapes persist_dir); got {namespace!r}. It "
            "names a store within persist_dir, not a path."
        )
    return namespace


def _split_persist_base(persist_path: str | Path) -> Path:
    """Derive the on-disk base from ``persist_path``: the binary index is
    written to ``{base}.tvim`` and the node side-car to
    ``{base}.nodes.json`` (extensions *appended* — see ``_with_ext``).

View on GitHub (pinned to ccab9f325e)

Solutions

1. Use a flat name (alphanumerics, dash, underscore, dots) — the namespace names a store within persist_dir, not a path.
2. Strip or encode directory components before passing the namespace.
3. Catch the ValueError in tooling to detect accidental path-like namespaces (also a path-traversal defense).

When it happens

Trigger: Thrown at turbovec-python/python/turbovec/llama_index.py:170 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of RyanCodrai/turbovec@ccab9f325e (2026-09-06). Data as JSON: /api/errors/096636719fd31a97. Report an issue: GitHub.