The config key that discarded my Chrome flags, and a hang that wasn't

In February 2026 I moved an invoicing app's deploys to a new deploy tool, and my notes from that week say every PDF it tried to make failed. The app renders each invoice as a web page and has headless Chrome print it, through Ferrum and a thin Rails wrapper around it, ferrum_pdf. Nothing failed quickly. The background job that builds finished invoices wraps the render in its own sixty-second timer, which cuts in before Ferrum's. The draft-invoice preview has no timer of its own, so it waits out Ferrum's ninety seconds and then raises the error I wrote down that week, a Ferrum::ProcessTimeoutError saying Browser did not produce websocket url. A minute or more of nothing, and an error that named no cause.

I chased the plausible causes first, and the fix commit still carries their marks. It changes how the app caches its IP rules. It sets a base-URL variable the new setup didn't have. It raises the container's memory limit from 512 MB to 1,280 MB. It removes three Chrome flags: single-process, disable-logging and disable-dev-tools. It also adds a 161-line rake task that walks the PDF pipeline one layer at a time, in six steps from system information to a real invoice template, with a stylesheet check in between. Step two is the one that matters here:

It isolates the layer, but on failure it prints the exception's class and message and nothing else. Hold on to that. None of the changes above was the cause. The cause was one word in the same diff.

My notes from that week describe a flag hunt, but its script was never committed, so I rebuilt the failure and ran it again. The rebuild uses the Chromium 144 build Debian's security archive was serving on 12 February 2026, the fix's ferrum and ferrum_pdf versions, the initializer's production branch as it stood on the morning of the fix, and the production image's non-root user, in Docker on an Apple-silicon Mac. That is not the production host, so every timing below is mine. The hunt keeps three flags as a baseline, adds the other 25 in groups of four, then tries each flag on its own inside any group that fails:

Every group failed, and so did every flag on its own. Even the baseline failed, with no suspects in it at all. When taking any one thing away changes nothing, the thing you are taking away isn't there. With the key corrected, the same hunt passes at every step, baseline included, in 0.24 to 0.34 seconds. On this build no flag is poisonous.

So I looked at what Ferrum actually launched. This is the live process list a moment after launch, one flag per line:

That is the command line Ferrum handed to Debian's chromium launcher script, which adds eight flags of its own before Chrome proper starts. All 39 are Ferrum's: its 35 defaults plus the debugging port, the address, the window size and a profile directory. Thirteen of my 28 flags are in there anyway, exactly as I wrote them, because Ferrum sends them by default. --no-sandbox is not one of them, and that is deliberate. In Ferrum's defaults it sits commented out, with a note:

With the right key, the same launch carries 53 flags, --no-sandbox among them, and the process is still alive a second later.

Here is what the production branch of config/initializers/ferrum_pdf.rb said on the morning of the fix, before it landed:

The wrapper keeps its settings in an ActiveSupport::OrderedOptions: a hash whose keys you read and write as methods, with no list of allowed names:

So config.browser_args = {…} is stored without error. When the wrapper starts a browser, it peels off the three keys it uses itself and hands everything else to Ferrum, unchecked:

Ferrum reads its Chrome flags from exactly one key, and an absent key is an empty hash:

Ferrum doesn't complain about keys it doesn't know either. I asked both layers directly:

Three of the keys I set were read by nothing at all: the flags, and two of the four timeouts. Until the fix, every revision of the production branch that had flags sent them to the same wrong key:

Across those revisions the list went from 21 flags to 36, then 17, then 28, and none of them reached Chrome through my config. Meanwhile browser_timeout went from 20 to 120, read by nothing. Of the timeouts, the one that mattered was process_timeout, and all it decided was how long Ferrum would wait.

The wrong word was mine, not the gem's. The wrapper's README, both the version I installed in August and the one I ran in February, shows config.browser_options = { "no-sandbox" => true } for Docker. browser_args was probably carried over from the previous PDF library, whose configuration called Chrome's flags args. It isn't a typo of the right key. It is a different word that sounds just as likely to be right.

The decisive change was that word, in both branches of the initializer:

The fix commit did more, but the rebuild shows the word alone is enough: with the right key, all 28 original flags and the old 512 MB limit, the PDF comes out in 0.55 seconds. My page there is a one-heading invoice, so all I'll claim is that the fix didn't need the extra memory.

Which leaves the awkward question. browser_args arrived on 16 August 2025 and the fix landed on 13 February 2026, so it sat in the file for 181 days. Why did it only break in February?

Because of a deploy script. Before the move, the app went out through a hand-rolled script whose docker run had carried two extra options since June 2025, under a comment that names Chrome and PDF generation:

Docker's default seccomp profile denies the system calls that create new namespaces unless the container holds CAP_SYS_ADMIN, and Chrome's Linux sandbox enters new PID and network namespaces. Those two lines let Chrome build its sandbox, so it never needed the --no-sandbox that wasn't arriving. In the rebuild, the wrong key with both options renders a PDF in 0.27 seconds. Either option alone was enough on my machine (0.35 seconds with only the seccomp option, 0.32 with only SYS_ADMIN), though I wouldn't promise that on every host kernel.

On 7 February 2026 I committed the move to the new deploy tool, and the old script went with it. Its config asked for a memory limit and nothing else:

Chrome was back under Docker's defaults. The bug didn't arrive in February: it had been in the file for 175 days, and with the commit of 7 February it lost its cover. I can't show that every PDF was healthy for those 175 days. What I can show is that, in my rebuild, the wrong key could not stop Chrome from starting while those two lines were there.

I'm not recommending them. SYS_ADMIN and an unconfined seccomp profile relax the whole container so that one browser can build its sandbox. The fix gets --no-sandbox to Chrome instead, which is what the wrapper's README shows for Docker, with the caveat that you should trust any sites visited. The same README recommends a Chrome seccomp profile over --no-sandbox for security, and that is the better place to end up.

A correction, and this one is on me. My notes from February say Chromium on ARM64 hangs while it sets up its sandbox, instead of crashing. Rebuilt with the same Debian Chromium 144 build as the hunt, on arm64, as the same non-root user, it doesn't hang:

Spawned directly, it aborts in about a tenth of a second. Launched through Ferrum it does the same: polled every couple of milliseconds, the process Ferrum spawned is a zombie 0.107 seconds in. And Ferrum's note about setting up a user doesn't cover this: the rebuild runs as a non-root user and still can't create the namespaces.

So the ninety seconds were Ferrum's. It points Chrome's output at a pipe and keeps the pipe's write end open in its own process until it is done:

Then it waits for Chrome to print its debugging address:

A pipe reports end-of-file only when every write end is closed. Chrome's copy closed when Chrome died. Ferrum's didn't, so wait_readable never sees end-of-file, and the loop checks the clock and the pattern but never whether the process is still alive. It waits the full process_timeout for a line from a process that is already gone.

With production's process_timeout of 90 seconds and the wrong key, the rebuild waited 90.03 seconds on a process that lived for 0.107, about 840 times longer than Chrome's whole life. With the right key, the same run rendered the PDF in 0.37 seconds. The message suggests raising :process_timeout, which here only makes the wait longer.

Where Ferrum reached the end of its own wait, in the draft preview and the diagnostic task, Chrome's own explanation (in the rebuild, Failed to move to new namespace, then a FATAL Operation not permitted) was inside the exception the whole time, in ProcessTimeoutError#output, and nothing in the app printed it. Ferrum would have written it to a logger:, had the app passed one. On the background job's path, rebuilt the same way, the job's own sixty-second timer fires first, so the error is Ruby's plain execution expired, and Chrome's output goes with it.

A few lines at boot would have named all three dead keys before the first request. This is the guard I ran in the rebuild, against ferrum 0.17.1:

That list is Ferrum 0.17.1's. Version 0.17.2 adds dockerize and 0.18.0 adds protocol_timeout, so a hard-coded list starts rejecting valid keys after an upgrade. Derive it in a spec instead, as the rebuild does by scanning Ferrum's options.rb for the keys it reads. The second check is the one the ps listing made: build the command line Ferrum will run and check it. The rebuild uses Ferrum's own command builder, so pin that to the version you run:

The third is the cheapest: when you rescue Ferrum::ProcessTimeoutError, log e.output, not just e.message. Newer Ferrum has a dockerize: option that adds --no-sandbox for you, but 0.18.0 still accepts unknown keys silently and still waits out process_timeout on a dead process.

The wrong key was mine, not either gem's; the README had the right key all along. What it shows is a shape that turns up wherever a wrapper forwards options it never checks to a library that ignores names it doesn't know: two layers that each accept anything, so a plausible wrong word is exactly as valid as the right one. For nearly six months a deploy script happened to cover for that word, and when the cover went, a launcher that never checks whether its child is alive turned a tenth-of-a-second crash into ninety seconds of silence. Check the command line your process actually got, not the one you configured. Print the output your errors carry. And when something hangs, ask what is waiting, and on whom.