bwrap: Unknown option --argv0

bwrap is bubblewrap, the unprivileged Linux sandbox that Codex uses to run commands in isolation. This message comes from bubblewrap’s own option parser, which means it failed while reading its command line — before it built a sandbox, before it entered a namespace, and before a single line of your code or the model’s code executed. Nothing was denied by a policy, nothing partially ran, and none of it involves your API key, your model, your network, or the project you are in.

The flag is fine. The binary is old.

“Unknown option” reads like a bug report waiting to be filed: the tool passed something bubblewrap does not accept, therefore the tool is wrong. That reading is almost always backwards.

An option parser saying “unknown” means exactly one thing: this build of this binary does not have that option. It is not a claim that the option is invalid, nonexistent, or misspelled. Codex constructs its command line for a bubblewrap that supports --argv0; the bubblewrap that answered is an older build that predates it.

That makes this a version mismatch of an unusual shape, and it is worth naming because it explains why the fix feels so unlike other CLI problems. A modern coding agent ships as a self-contained binary precisely so it does not depend on what your machine has. The sandbox is the one dependency it cannot vendor, because a sandbox has to be the system’s — it needs the kernel’s cooperation and the system’s own helper. So one component of the tool is as new as today’s release and another is as old as the day your distribution froze.

The second half of the judgement saves more time than the first: on a long-term-support distribution, updating your packages will not fix this. LTS releases hold packages at the version they shipped with and backport security fixes, not new features. apt update && apt upgrade will run happily, report everything is current, and leave you with the same bubblewrap. People conclude the tool is broken at this point, because their system is by its own account fully up to date.

Is retrying useful?

No. Argument parsing is deterministic.

The same binary reads the same flag and rejects it the same way, every time, with no dependence on load, network, or time of day. There is no backoff that helps, and there is nothing to wait for.

If it does succeed intermittently, do not treat that as luck — treat it as evidence. It means two different bubblewrap binaries are being resolved depending on how the process was started: a login shell versus a non-login shell, a terminal versus an editor-spawned process, inside a container versus on the host. That is a PATH question with a concrete answer, not a flaky sandbox.

Establishing which bubblewrap answered

command -v -a bwrap lists every bubblewrap your PATH can reach. More than one entry means the resolution order decides your outcome, and the one you inspect by hand may not be the one Codex launches.

bwrap --version identifies the build. Note it, but do not go hunting for a table of which release added which flag — there is a better test.

bwrap --help is the decisive one. If --argv0 does not appear in the help output of the binary that Codex is actually running, you have confirmed the cause with no version archaeology at all. This test survives releases, which is more than any version number in a forum thread can say.

Does the same tool work elsewhere? On a newer machine, a newer container image, or a newer WSL distribution. If it does, you have confirmed the problem is environmental rather than anything in your config or your account, which is worth knowing before you start editing settings that cannot possibly be the cause.

Fixing it, in the order worth trying

Get a newer bubblewrap. Package names and channels differ by distribution, so check your distribution’s package index rather than copying a command from somewhere; what you are looking for is a channel that carries something newer than the frozen stable pocket. Confirm the result the same way you diagnosed it: --argv0 appears in bwrap --help.

Move the work to a newer base. If the machine is managed or the image is locked, the sandbox can come from an image instead of the host. A container built on a newer base image, a newer distribution release, or a newer WSL distribution all give you a modern bubblewrap without touching the host’s package set. In CI this is the durable fix, because CI images get rebuilt and a pinned modern base keeps the problem from returning.

Do not run the agent as root to get around it. This is worth stating as logic rather than as a rule: root does not add a missing command-line option to a binary. It cannot fix this error, and it spends the sandbox’s entire reason for existing to achieve nothing. Bubblewrap is designed to work unprivileged; that is the point of it.

Turning the sandbox off is the last option, and it has a price. If you cannot change the image and cannot change the package, Codex can run without its own sandbox — and what you lose is the boundary that was going to keep a generated command away from the rest of the machine. That trade is defensible when the process is already inside a disposable boundary: an ephemeral CI container with no long-lived credentials mounted, or a throwaway VM. It is not defensible on the laptop that holds your SSH keys and every repository you have write access to. Take the current setting names from the Codex documentation (learn.chatgpt.com/docs, indexed from developers.openai.com/codex/llms.txt) rather than a blog post — sandbox and approval settings are among the fastest changing parts of the CLI, and a stale flag from a screenshot is how people end up disabling more than they meant to.

Confirming the fix

The absence of the error message is not confirmation — it is possible to remove it by removing the sandbox. Confirm two things instead.

First, bwrap --help on the binary that Codex resolves lists --argv0. Second, let Codex actually run a trivial command that produces visible output, and check that it reports operating with its sandbox rather than without it. A sandbox that starts and runs one command has demonstrably passed both the parsing stage and the namespace stage, which is more than the first test alone proves.

If it clears the parser and then fails while setting up the namespace, you have moved one step forward into a loopback failure inside the network namespace, which is the kernel refusing a capability rather than the binary refusing a flag — a different page with a different set of trade-offs.

The sandbox errors in this cluster all arrive as low-level Linux complaints that never mention the tool, which makes them hard to search and easy to misfile. The loopback EPERM happens after option parsing succeeds, and points at your container runtime or kernel policy. A missing sandboxPolicy field names the sandbox but is not a sandbox denial at all — it is two components of the tool disagreeing about a message. If you are holding a message that mentions bubblewrap and are not sure which stage failed, the AI coding error triage tool sorts them by how far the sandbox got.