openai/codex · critical

bubblewrap is unavailable: no system bwrap was found on PATH

Error message

bubblewrap is unavailable: no system bwrap was found on PATH and no bundled codex-resources/bwrap binary was found next to the Codex executable

What it means

exec_bwrap requires a bubblewrap launcher: a system bwrap discovered on PATH (a file whose --help advertises --as-pid-1 and --perms) or a bundled codex-resources/bwrap binary next to the Codex executable. When neither is found, preferred_bwrap_launcher() returns Unavailable and exec_bwrap panics, so the Linux sandbox cannot start on that host at all.

Source

Thrown at codex-rs/linux-sandbox/src/launcher.rs:51

    supports_argv0: bool,
    supports_perms: bool,
    supports_ro_bind_fd: bool,
}

pub(crate) fn exec_bwrap(mut argv: Vec<String>, preserved_files: Vec<File>) -> ! {
    argv.insert(1, "--as-pid-1".to_string());

    match preferred_bwrap_launcher() {
        BubblewrapLauncher::System(launcher) => {
            if !launcher.supports_ro_bind_fd {
                translate_legacy_bwrap_fd_mounts(&mut argv)
                    .unwrap_or_else(|error| panic!("invalid legacy bubblewrap fd mount: {error}"));
            }
            exec_system_bwrap(&launcher.program, argv, preserved_files)
        }
        BubblewrapLauncher::Bundled(launcher) => launcher.exec(argv, preserved_files),
        BubblewrapLauncher::Unavailable => {
            panic!(
                "bubblewrap is unavailable: no system bwrap was found on PATH and no bundled \
                 codex-resources/bwrap binary was found next to the Codex executable"
            )
        }
    }
}

fn translate_legacy_bwrap_fd_mounts(argv: &mut Vec<String>) -> Result<(), String> {
    let command_separator = argv
        .iter()
        .position(|argument| argument == "--")
        .ok_or_else(|| "bubblewrap argv is missing the command separator '--'".to_string())?;
    let mut verification_args = Vec::new();
    let mut verified_fds = Vec::new();
    let mut argument_index = 0;

    while argument_index < command_separator {
        if argv[argument_index] != "--ro-bind-fd" {

View on GitHub (pinned to 339751715c)

Solutions

1. Install bubblewrap: apt-get install -y bubblewrap (Debian/Ubuntu), dnf install -y bubblewrap (Fedora), pacman -S bubblewrap (Arch)
2. Verify the probe passes: bwrap --help must list --as-pid-1 and --perms
3. Fix the PATH of the service or container to include the bwrap directory
4. If you distribute codex, bundle codex-resources/bwrap next to the executable

Example fix

# before -- slim container, no bubblewrap
FROM debian:bookworm-slim

# after -- bubblewrap present and on PATH
FROM debian:bookworm-slim
RUN apt-get update \
    && apt-get install -y --no-install-recommends bubblewrap \
    && rm -rf /var/lib/apt/lists/*

fn bubblewrap_usable() -> bool {
    std::process::Command::new("bwrap")
        .arg("--help")
        .output()
        .map(|o| {
            let t = format!(
                "{}{}",
                String::from_utf8_lossy(&o.stdout),
                String::from_utf8_lossy(&o.stderr)
            );
            t.contains("--as-pid-1") && t.contains("--perms")
        })
        .unwrap_or(false)
}

if !bubblewrap_usable() {
    run_without_linux_sandbox()?; // graceful degradation instead of panic
}

When it happens

Trigger: Invoking sandboxed execution on a host with no bubblewrap installed; a service or container whose PATH omits the directory containing bwrap; a bwrap binary that fails its --help probe or lacks --perms; packaging that ships the codex binary without codex-resources/.

Common situations: Minimal Docker or CI images (slim, distroless); systemd units with a reset PATH; ancient or broken bubblewrap installs; relocating the codex executable away from its bundled resources.

Related errors

• invalid legacy bubblewrap fd mount: {error}
• failed to open bundled bubblewrap {}: {err}
• failed to exec bundled bubblewrap {} via {fd_path}: {err}
• InvalidInput
• PermissionDenied

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