{"record":{"id":"27ccb1c142969468","repo":"usestrix/strix","slug":"unknown-strix-runtime-backend-name-r-supported","errorCode":null,"errorMessage":"Unknown STRIX_RUNTIME_BACKEND: {name!r} (supported: {supported})","messagePattern":"Unknown STRIX_RUNTIME_BACKEND: (.+?) \\(supported: (.+?)\\)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"strix/runtime/backends.py","lineNumber":71,"sourceCode":"_BACKENDS: dict[str, SandboxBackend] = {\n    \"docker\": _docker_backend,\n}\n\n_BIND_MOUNT_BACKENDS: set[str] = {\"docker\"}\n\n\ndef get_backend(name: str) -> SandboxBackend:\n    \"\"\"Return the backend factory for ``name`` or raise.\n\n    Args:\n        name: Backend identifier (e.g. ``\"docker\"``). Match is exact;\n            no fallback. Unknown values raise so config typos surface\n            immediately instead of silently picking a default.\n    \"\"\"\n    backend = _BACKENDS.get(name)\n    if backend is None:\n        supported = \", \".join(sorted(_BACKENDS))\n        raise ValueError(\n            f\"Unknown STRIX_RUNTIME_BACKEND: {name!r} (supported: {supported})\",\n        )\n    logger.debug(\"Selected sandbox backend: %s\", name)\n    return backend\n\n\ndef register_backend(\n    name: str,\n    backend: SandboxBackend,\n    *,\n    supports_bind_mounts: bool = False,\n) -> None:\n    \"\"\"Register a custom backend under ``name``.\n\n    Intended for downstream users who ship their own runtime — register\n    before any ``session_manager.create_or_reuse`` call. Re-registering\n    an existing name overwrites the prior entry. ``supports_bind_mounts``\n    defaults to False: a remote runtime cannot see the caller's filesystem, so","sourceCodeStart":53,"sourceCodeEnd":89,"githubUrl":"https://github.com/usestrix/strix/blob/85513391305171ecc6faffe03da4a8bda5e3febb/strix/runtime/backends.py#L53-L89","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use exactly one of the names printed in the error's '(supported: ...)' list — usually 'docker' — respecting case.","Unset STRIX_RUNTIME_BACKEND entirely to accept the documented default (docker).","If you expected an extra backend, verify your Strix version/optional extras register it (check strix/runtime/backends.py registrations).","Search the environment for where the variable is set: env | grep STRIX_RUNTIME_BACKEND, .env files, CI secrets."],"exampleFix":"# before\nexport STRIX_RUNTIME_BACKEND=Docker   # or 'dockerr'\n\n# after\nexport STRIX_RUNTIME_BACKEND=docker    # exact, lowercase, registered name","handlingStrategy":"validation","validationCode":"from strix.runtime.backends import _BACKENDS  # or a public accessor if available\nimport os\n\nname = os.environ.get(\"STRIX_RUNTIME_BACKEND\", \"docker\")\nif name not in _BACKENDS:\n    raise SystemExit(f\"bad backend {name!r}; supported: {sorted(_BACKENDS)}\")","typeGuard":null,"tryCatchPattern":"from strix.runtime.backends import get_backend\ntry:\n    backend = get_backend(name)\nexcept ValueError as exc:\n    # fail fast at startup with the supported list; do not silently substitute\n    raise SystemExit(str(exc))","preventionTips":["Use lowercase exact names; the lookup is case-sensitive by design.","Validate the variable once in your launch script/CI before starting a scan.","Unset the variable when the default (docker) is intended — don't restate it and risk typos."],"tags":["config","environment","runtime","sandbox","startup"],"backgroundTag":null,"analyzedSha":"85513391305171ecc6faffe03da4a8bda5e3febb","analyzedAt":"2026-08-15T05:03:57.275Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}