openai/codex · error · ValueError

sandbox must be one of: {options}

Error message

sandbox must be one of: {options}

What it means

Error "sandbox must be one of: {options}" thrown in openai/codex.

Source

Thrown at sdk/python/src/openai_codex/_sandbox.py:33

class Sandbox(str, Enum):
    """Preset filesystem access levels for threads and turns.

    `read_only` allows file reads without writes. `workspace_write` is the
    normal default for projects with a recorded trust decision and allows
    writes inside the workspace and configured writable roots. `full_access`
    removes filesystem access restrictions.
    """

    read_only = "read-only"
    workspace_write = "workspace-write"
    full_access = "full-access"


def _require_sandbox(sandbox: Sandbox) -> None:
    if isinstance(sandbox, Sandbox):
        return
    options = ", ".join(f"Sandbox.{value.name}" for value in Sandbox)
    raise ValueError(f"sandbox must be one of: {options}")


def _sandbox_mode(sandbox: Sandbox | None) -> SandboxMode | None:
    """Translate a public preset to the thread lifecycle wire mode."""
    if sandbox is None:
        return None
    _require_sandbox(sandbox)

    match sandbox:
        case Sandbox.read_only:
            return SandboxMode.read_only
        case Sandbox.workspace_write:
            return SandboxMode.workspace_write
        case Sandbox.full_access:
            return SandboxMode.danger_full_access
        case _:
            return _assert_never_sandbox(sandbox)

View on GitHub (pinned to 339751715c)

Solutions

1. Pass one of the sandbox options listed in the message.

When it happens

Trigger: Thrown at sdk/python/src/openai_codex/_sandbox.py:33 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of openai/codex@339751715c (2026-08-25). Data as JSON: /api/errors/be1118e017a2debd. Report an issue: GitHub.