usestrix/strix · error · ValueError

Unknown STRIX_RUNTIME_BACKEND: {name!r} (supported: {support

Error message

Unknown STRIX_RUNTIME_BACKEND: {name!r} (supported: {supported})

What it means

The sandbox backend registry resolves STRIX_RUNTIME_BACKEND by exact match with no fallback; an unregistered name raises ValueError listing the supported backends. This is deliberate: config typos must surface immediately rather than silently selecting docker (the default when the variable is unset).

Source

Thrown at strix/runtime/backends.py:71

_BACKENDS: dict[str, SandboxBackend] = {
    "docker": _docker_backend,
}

_BIND_MOUNT_BACKENDS: set[str] = {"docker"}


def get_backend(name: str) -> SandboxBackend:
    """Return the backend factory for ``name`` or raise.

    Args:
        name: Backend identifier (e.g. ``"docker"``). Match is exact;
            no fallback. Unknown values raise so config typos surface
            immediately instead of silently picking a default.
    """
    backend = _BACKENDS.get(name)
    if backend is None:
        supported = ", ".join(sorted(_BACKENDS))
        raise ValueError(
            f"Unknown STRIX_RUNTIME_BACKEND: {name!r} (supported: {supported})",
        )
    logger.debug("Selected sandbox backend: %s", name)
    return backend


def register_backend(
    name: str,
    backend: SandboxBackend,
    *,
    supports_bind_mounts: bool = False,
) -> None:
    """Register a custom backend under ``name``.

    Intended for downstream users who ship their own runtime — register
    before any ``session_manager.create_or_reuse`` call. Re-registering
    an existing name overwrites the prior entry. ``supports_bind_mounts``
    defaults to False: a remote runtime cannot see the caller's filesystem, so

View on GitHub (pinned to 8551339130)

Solutions

1. Use exactly one of the names printed in the error's '(supported: ...)' list — usually 'docker' — respecting case.
2. Unset STRIX_RUNTIME_BACKEND entirely to accept the documented default (docker).
3. If you expected an extra backend, verify your Strix version/optional extras register it (check strix/runtime/backends.py registrations).
4. Search the environment for where the variable is set: env | grep STRIX_RUNTIME_BACKEND, .env files, CI secrets.

Example fix

# before
export STRIX_RUNTIME_BACKEND=Docker   # or 'dockerr'

# after
export STRIX_RUNTIME_BACKEND=docker    # exact, lowercase, registered name

from strix.runtime.backends import _BACKENDS  # or a public accessor if available
import os

name = os.environ.get("STRIX_RUNTIME_BACKEND", "docker")
if name not in _BACKENDS:
    raise SystemExit(f"bad backend {name!r}; supported: {sorted(_BACKENDS)}")

from strix.runtime.backends import get_backend
try:
    backend = get_backend(name)
except ValueError as exc:
    # fail fast at startup with the supported list; do not silently substitute
    raise SystemExit(str(exc))

When it happens

Trigger: Exporting STRIX_RUNTIME_BACKEND to a misspelled or unavailable backend name, e.g. 'dockerr', 'Docker' (case-sensitive), or a backend whose registration entry point didn't load. get_backend() is called during runtime/sandbox construction, so it fails at scan startup.

Common situations: Typo in .env or CI variables; uppercase/lowercase mismatch (match is exact); referencing a backend that only registers when an optional dependency or container profile is installed; copy-pasting docs for a newer Strix version against an older install.

Related errors

• The interactive interface could not start: {exc}
• Docker not available
• Invalid Caido URL: {base_url}
• No LLM model configured. Set STRIX_LLM env or pass model= to
• strix_image is not configured. Set it in ~/.strix/cli-config

AI-assisted analysis of usestrix/strix@8551339130 (2026-08-15). Data as JSON: /api/errors/27ccb1c142969468. Report an issue: GitHub.