DEV Community: Piotr Hałas

Debugging PHP in Docker with an AI Agent and Xdebug

Piotr Hałas — Wed, 09 Sep 2026 15:54:56 +0000

For a while now I have used LLMs to automate parts of my work. One of those parts is debugging hard problems with Xdebug. Before, I set the breakpoints by hand and built complicated requests to see what happens inside. It usually took a few requests, and I had to move the breakpoints again and again. Then I found that PhpStorm has Xdebug in its MCP server. For simple GET requests, that is enough. But it fails on endpoints that need authorization, and on any method other than GET. So I did not wait for JetBrains. I wrote my own small MCP server, and it makes this work much faster. I share this tool with you, and I hope it helps you too — especially if you work with Docker.

TL;DR

Tired of reading, and you have not started yet? Fair enough. Straight to setting up the MCP server in PhpStorm, or straight to installing xdbg.

AI agents are good at debugging from code alone — until the bug lives in runtime state. Then you need Xdebug, and every existing Xdebug tool is built for humans clicking through a GUI. PhpStorm ships an MCP server since 2025.2, but it is GET-only, has no headers, no path for CLI in Docker, and no control over Xdebug inside the container. So I built xdbg: an MCP server that gives an agent the full loop — enable Xdebug, set a breakpoint, fire a real request, step, inspect, detach.

MIT licence, one-line install, works with Claude Code, opencode, Cursor and any MCP-capable client. Source: github.com/crazy-goat/xdbg
Written against xdbg v0.1.1 (Go 1.26), Docker 29.7.2 / Compose 5.5.0, and any PHP 8 image with Xdebug 3. PhpStorm checked on 2025.2 and again on 2026.2.1.

The mighty duo: var_dump and die

This is the standard. You need to check something fast, so you print the value and stop the script. It is quick, it always works, and it needs no setup.

function add(int $a, int $b): int
{
    $result = $a + $b;
    var_dump($result);
    die();
}

It also has costs. You are editing the code in order to debug it, and you only see the one place you thought to print. Inside a loop, var_dump fills the screen a thousand times and you scroll for the single line that matters. And die() gives you exactly one breakpoint: it kills the process on the spot, so you cannot continue and see what came after it. That hurts most in an event loop, where the state you actually want often shows up on the second pass — and die() never lets you get there.

Analysis by an LLM

Most bugs come straight from the code, and an LLM finds those much faster than any debugger. You paste the stack trace, you show the file, and you have an answer in seconds. But this method has a clear limit. With harder problems, with your own framework, or with anything the model has not seen before, there is a real chance the LLM will invent a problem instead of finding the one you have.

For example, this one. php-fpm kept dying with a segfault, but only on Colima. The LLM was sure the fault sat in the container runtime: first Colima, then Podman, then Rosetta. Every answer sounded reasonable, and every one of them was wrong. It changed its mind only after I asked it to write a test — and then it found that the bug was in PHP itself, and had been there for years. The story of that hunt is here.

The two lines in question, in ext/opcache/shared_alloc_mmap.c. OPcache now reserves requested_size + huge_page_size before it remaps the block with MAP_HUGETLB, so a kernel that fails halfway cannot leave a hole behind. Nothing an agent could have guessed from my application code. Click to open full size.

And a made-up answer looks exactly like a correct one, so you need a cheap way to tell the two apart.

Debugging with tests

That cheap way is a test. Ask the LLM to write one that proves the problem is real: if it was right, the test fails for exactly the reason it gave you, and if it made the problem up, the test passes and you have lost two minutes. Either way you now know, and you also keep the test. From my experience, a bug is very often a feature that somebody forgot about. A test written this way also writes that feature down, so the next person does not have to guess what the code was supposed to do. It costs a little more time than a quick print, and it gives that time back later.

But some bugs are very hard to put into a test. The state that breaks them only exists in the running system — the real database, the real queue, the real timing, a service that answers differently today than it did yesterday. A test has to pretend all of that, and it pretends what you already believe. For bugs like these you have to look at the living thing, so you need something else.

Manual debugging in the IDE

That something else is a real debugger. For a human the most comfortable one is an IDE like PhpStorm. You set the breakpoint by hand, you fire the request, and you walk through the code line by line, looking at the state as you go. It works, and for a long time it was the only way. But it has costs. You have to know where to put the breakpoint before you know what is wrong, so if you guess badly you start again. Every repeat means the same clicks: listen, fire the request, step, look. And one wrong choice — step into instead of step over — can cost you a lot of time, because now you are ten frames deep inside framework code you never wanted to see.

A real session: stopped at StreamConnection.php:154, three frames deep, with $this open. Every part of this I had to ask for by hand — where the breakpoint goes, when to run, and each step after that. Click to open full size.

And here is the part that annoys me most, which is not PhpStorm’s fault at all: I forget to turn the debugger off. Then I run the tests, or a linter, or just one ordinary request, and the process stops somewhere for no visible reason. The classic version goes like this. I have tested the fix, it works, so I tell myself: full test suite and then I am done for the day. I start the suite and go to make a drink, because the suite takes a while. I come back, and nothing has moved — the tests are sitting on a breakpoint. Then I complain quietly to myself for forgetting again. I would like to blame my memory, and at my age that excuse comes more easily every year. There must be a better way.

The simplest path: PhpStorm MCP

And there is. The fastest path to automating Xdebug is PhpStorm — since version 2025.2 it ships with its own MCP server. Go to Settings → Tools → MCP Server, click Enable MCP Server, auto-configure the client — Claude Code, Cursor, opencode — and you are in the game. The plugin is installed by default, so there is nothing to fiddle with.

A predefined set of Xdebug tools is ready out of the box: setting breakpoints (xdebug_set_breakpoint), starting a PHP server (xdebug_start_server), making URL requests (xdebug_request), stepping through code (xdebug_step_into, xdebug_step_over, xdebug_step_out), inspecting the stack and context. You start a debugging session without leaving the chat — like opening the fridge and discovering there is a warm dinner inside.

The flow is different from manual debugging. Instead of clicking around yourself and deciding where to place a breakpoint, you write a prompt describing the problem and ask the agent to use Xdebug through PhpStorm to find the cause. The agent analyses the code, sets breakpoints on its own where it suspects the problem, then drives the session step by step: reads the stack, inspects variables, dives deeper into calls. If the runtime goes down a different path than expected, it moves the breakpoint, repeats the request, and analyses again. All by itself.

For a start this is close to ideal. But in its current form it comes with a few limits, and they are not small print — they change how you work.

Where PhpStorm MCP stopped being enough

None of what follows is a complaint about PhpStorm — it is a very good IDE and its MCP server does what it set out to do. It is a description of the shape of our problem, which happens to sit outside that shape. I first hit this on PhpStorm 2025.2, and it is still the same on 2026.2.1 — four releases later.

The biggest one is simple: PhpStorm has to be open, and it has to be open on the right project. The MCP server is the IDE, so the debugger only exists while the window is running and pointing at the code you care about. Switch project, or close the IDE to free some memory, and the agent loses its tools in the middle of a session. It also means the agent shares the debugger with you: your breakpoints, your listening state, your run configurations.

The next thing is not really a flaw at all: not everyone has PhpStorm. It is currently the default IDE for many PHP developers, but let us be honest — for people starting their careers the licence can be too expensive, and some simply prefer something else. For them this path is dead from the first minute — a party they cannot enter because they are not on the list.

The rest is about what it does not reach — and almost all of it comes down to one thing: it works as if Docker were not in the picture:

No control over Xdebug inside the container. PhpStorm MCP does not enable or disable Xdebug in the container — and by default we keep it disabled, because it slows everything down: requests, CLI, tests. Without automatic toggling it is easy to forget to turn it off, and then phpunit, phpstan or composer install stop on breakpoints.
Host ↔︎ container paths. The MCP surface works in host paths — hand it a container path like /var/www/app/src/Kernel.php and it refuses outright with File not found. That part is honest. The trap is what comes next: pass the host path and you get back "Breakpoint created.", but whether that breakpoint ever hits depends on path mappings configured on the IDE side, which the agent cannot see, verify or repair. It receives a confident success and then silence — and starts moving the breakpoint one line at a time trying to work out why nothing stops.
No path to a command already running in a container. Debugging bin/console app:foo inside Docker is possible, but only through a run configuration someone created by hand in the GUI, backed by a docker-compose interpreter. The MCP surface cannot create one, and xdebug_start_debugger_session takes only an existing configuration or a local filePath + line — there is no attach-to-running-process mode. So a worker or a cron job that is already executing is out of reach.
GET only, no headers. xdebug_request supports only GET and does not allow setting headers. In real API work — POST/PUT/PATCH with JSON, a JWT in Authorization, cookies, Content-Type — that is simply not enough.
The port is held for the whole session. PhpStorm MCP starts a session and keeps port 9003 occupied until you turn it off yourself. The agent often forgets, then runs tests — which hang on breakpoints because Xdebug keeps stopping the runtime.
Conflicts on port 9003. When the port is occupied you have to manually work out what is listening and which tool is holding the connection.
No good documentation. The official docs list the functions but do not describe the process — how to combine them into a working flow. The LLM knows what tools exist, but has to figure out by itself how to use them in practice.

If not PhpStorm, then what?

Two MCP servers for Xdebug already existed, and it is worth knowing what they do. koriym/xdebug-mcp is trace-first — forward traces, profiling, coverage — and reaches containers by wrapping a command you hand it: xstep --break=… -- docker compose run --rm php …. Its code excludes php-fpm and php-cgi on purpose: CLI binaries only. kpanuragh/xdebug-mcp is closer to interactive debugging — breakpoints, stepping, watches — with proper container path translation configured through a static PATH_MAPPINGS map.

Both of them miss the part I needed. Neither turns Xdebug on and off inside a running container, so you leave it enabled and then wonder why phpunit hangs. Neither fires the request either — you still bring your own trigger, and for a POST with a 1600-byte bearer token that trigger is most of the problem. So with either one, there is still no way to debug an ordinary web request going through php-fpm in Docker, which is what I do most days.

The older tools do not close it either. phpdbg, PHP’s built-in CLI debugger; debugclient, the DBGp client shipped with Xdebug; editor integrations such as VS Code PHP Debug — all of them are designed more for humans than for AI. Each works interactively: typing commands, clicking through a GUI, managing the session by hand. Great for debugging by a human, terrible as an interface for an agent that needs a programmable, automated API.

So I had no choice but to vibe-code my own tool. I had a working prototype after 10 minutes and a usable tool within an hour, using only open-source models available through opencode — which significantly reduced the cost. Funnily enough, writing this article took me longer than preparing xdbg together with the repo and docs.

What the tool actually needed

At first I only wanted xdbg_request, because that was what I needed most, with minimal requirements: GET/POST/PUT/… and passing headers. Coding went smoothly. But it quickly turned out that firing requests is only half the job.

The other half is knowing whether Xdebug is even enabled. Hence xdbg_container_status, xdbg_container_enable, xdbg_container_disable. Enabled Xdebug reduces performance and can block calls such as phpunit. On top of that, the agent would often set a breakpoint, start debugging, and execution never paused — so it would rack its brain over what happened, burning through mountains of tokens on guesswork.

Then came the authorization problem. Debugging very often ended with a 401. First thought: the token expired. I generated another one, it seemed to work, and a moment later there was another 401. It took me a while to realise that our token is around 1600 bytes long and the LLM simply slips when copying it into an MCP function. The same happened when a longer JSON body had to be prepared for a POST.

That is when I came up with passing the body and headers through files. A long token can be prepared in a file, and the JSON can be safely validated with something like jq before sending. That is how xdbg_request_from_files was born — and most of my request problems magically disappeared.

Next: running commands. Very often, to confirm something, it is faster to prepare a simple PHP or Symfony command on the side containing only the minimal code that actually reproduces the problem — instead of entering the whole application, placing breakpoints in five places and praying that the flow reaches the right one. The command has to run inside a Docker container, which created another challenge. With xdbg_run_command this became ridiculously simple: the agent enters the container by itself, runs the command, takes over the session, and you watch it play out.

Finally: manual triggers. Sometimes it is simply easier to trigger something by hand — when a command is started by a scheduler, or when a request comes from the outside through a webhook that is not easy to reproduce from the agent level. Every attempt to force the agent to create such a command ended with wonderful constructions like curl -X POST with three escaped brackets and a pipe to php -r. That is where xdbg_listen came from: the agent arms the listener, and you just snap your fingers and trigger whatever needs triggering.

In total there are more than twenty xdbg_* functions, and for agents that was a problem in itself — they often mixed up the call order, used xdbg_listen instead of xdbg_request, and got lost in the debugging flow like a customer in IKEA without a map. To make life easier for LLMs I added a dedicated skill that shows how to debug and which function is for what: an instruction manual you read once and then know which screw goes where.

Installation

Instead of reading ten pages of documentation and typing flags manually, paste one line into a chat with Claude Code or opencode:

Install and configure this MCP server for me:
https://raw.githubusercontent.com/crazy-goat/xdbg/main/install.md

And that is it. The agent fetches the guide, reads it, installs via go install, adds entries to the MCP configuration, translates host paths into container paths, adjusts flags for your project — and asks for permission before changing anything. Like a good assembly crew: they come in, measure, cut, set things up, and you only point to where the fridge stands.

On top of that, xdbg provides a dedicated AI skill (skills/xdbg/SKILL.md) with context about debugging flows, error recovery and good practices. The skill is installed separately, following the rule that the agent asks before installing — but thanks to it the agent knows which functions to use and in what order, instead of guessing.

What it looks like in practice

You are probably wondering what this kind of agent work looks like in real life — whether you can really debug without touching the IDE, or whether this is just a marketing pitch.

Click to open full size. Solid arrows stay inside one side; dashed ones cross the host/container boundary.

Here is the shape of it. The agent never talks to Xdebug directly — xdbg sits in the middle, holds the DBGp listener on port 9003, and translates between the MCP calls the agent makes and the debugger protocol the container speaks. Path translation happens in the same place, which is what stops the agent from setting breakpoints on host paths that the container has never heard of.

Watch the demo (MP4, 45s)

The agent is asked whether the add endpoint writes anything to stderr. It enables Xdebug, breaks in Calculator::add, fires the request, and steps until it finds the culprit — 45 seconds, one chat.

A Slim app with a simple GET /calc/add/{a}/{b} endpoint. For larger results, a log suddenly appears in stderr, even though nobody asked for it to be written there. The agent enables Xdebug inside the container, sets a breakpoint in Calculator::add, fires the request — and then drives the session step by step: reads the stack, inspects variables, dives into calls, evaluates expressions, and finds logLargeResult writing to php://stderr on its own. Everything in one chat, without switching tools, without the usual Postman-and-IDE loop.

The pattern is always the same:

enable Xdebug → breakpoint → request or command → step → detach → disable Xdebug

The agent takes care of cleanup by itself — it knows to close the session and free port 9003 before running tests. For HTTP, CLI and manual launch the flow is identical; only the trigger changes.

That flow leaves out one thing worth knowing. While the code is stopped, the agent can also change values, not only read them. Set a variable to whatever the failing case would produce, then continue — and you get to watch the unhappy path without building it first. A service that is healthy today but returns an error on Fridays, a payment that comes back declined, an empty result from a query that always finds rows on your machine. By hand this means clicking through the IDE and doing it again on every single run. The agent does it in one step, and it remembers what it already tried.

Summary

xdbg does not try to replace PhpStorm. It tries to pull debugging out of the IDE and put it where it fits the present: into a chat with AI. Between tracing where an exception escaped and discovering where it came from there is an entire afternoon of manual work — and xdbg turns that into a few prompts.

It is a small project on purpose. It solves one problem — driving Xdebug inside a container from an agent — and it has no ambition to grow past that. If JetBrains ships this properly in PhpStorm, or if one of the other MCP servers grows the container side, I will stop developing it and use theirs. A tool that exists because of a gap should disappear when the gap does.

MIT licence, Go, one-line installation. Worth trying and judging for yourself: github.com/crazy-goat/xdbg.

I spent a full day on a “five-minute” Docker migration

Piotr Hałas — Sat, 29 Aug 2026 19:03:41 +0000

We ditched Docker Desktop for Colima — and then PHP started segfaulting. A story about a simple migration that was not simple. On the way: a free tool that was not really free, a segfault with no logs, and a kernel that breaks its own contract. It ends deep inside the Linux syscall table — with a fix you can copy in five minutes.

TL;DR

php-fpm exits 139 (SIGSEGV) on Colima — silently, about a second after start, while the PHP CLI stays perfectly fine. OPcache asks the kernel for huge pages, the kernel half-performs the mapping before failing, and Rosetta falls into the hole it leaves behind. Jump straight to the fix →

Easiest fix: opcache.preferred_memory_model=shm — one ini line, works on both Colima and Podman. Running many amd64 containers on Colima? The seccomp profile below fixes it machine-wide instead, so you don’t have to touch every image’s config.

Tested on Colima 0.10.3 (vmType: vz, rosetta: true), macOS 26.6.2 on Apple Silicon, stock amd64 PHP 8.2 / 8.3 / 8.4 images. Running native arm64, or left rosetta: false? This bug does not touch you — which is exactly why a colleague on the same team “does not have it”.

The invoice that never came

It all started with a company decision. Docker Desktop is free for small companies. But when a company grows big enough, it must pay for every developer who uses it. Our company was getting close to that line. Nobody had paid anything yet — the invoice was still in the future. But it was clear that the invoice was coming, and that it would grow with every new hire.

So the decision was made early, before the first payment: we move to something free. It is much easier to migrate when you are not in a hurry. And honestly, the tool we would pay for is just a nice wrapper around free software. Paying for it felt strange.

Free for me, but I am a team player

Here is the funny part. This decision was not really about me. I work as a B2B contractor. My own little company is one person: me. By Docker’s own rules, a company this small can use Docker Desktop for free. Legally, I could keep it forever and pay nothing. Nobody would come after me.

But I did not want to be the special one. When one person in the team runs a different setup, small problems start. And this time, the problems would be mine, not theirs. The README would stop being true for me. New scripts would break on my machine only. Every little change in the stack would cost me an hour of debugging, alone. I did not want to be that person. So I decided to migrate like everyone else.

Podman: close, but no socket

The first idea was Podman. It is free, it is popular, and people say it is a drop-in replacement for Docker. So we tried it. It was not a drop-in replacement for us. Not even close.

The first problem was our SSH agent. Our docker-compose.yml mounts a special socket file into the PHP container: /run/host-services/ssh-auth.sock. Thanks to this socket, composer install inside the container can talk to our private GitLab over SSH. Here is the catch: this path is not a Docker feature. It is a Docker Desktop feature. Podman does not have it. Our composer.json has more than ten private repositories, so without the agent, nothing installs.

The second problem was host.docker.internal. Our PHP image has xdebug.client_host=host.docker.internal inside its config. Xdebug connects from the container to the host, where the debugger listens. With Podman, this name does not exist. Podman has its own name, host.containers.internal. The result: no debugging at all. Not in the browser, not for CLI commands. No error. Just silence.

The third problem was our Git worktrees. Every worktree has its own docker-compose.override.yml. These files use modern Compose features: top-level name: and the !override tag. The Python tool podman-compose cannot parse these files at all. It just crashes with a YAML error.

And there were small cuts too. For example, our lint script checks if the file /.dockerenv exists, to know if it runs inside a container. Podman does not create this file. It creates /run/.containerenv instead. Small thing. Easy to fix. But it was one more fix on the list.

Every single problem had a solution. But together they meant one thing: we would have to change shared files, shared scripts, and the habits of every developer. That is exactly the cost we wanted to avoid. So we looked somewhere else.

Colima: boring, and that is the point

Then we looked at Colima. Colima is different from Podman in one important way. Podman is its own engine that tries to act like Docker. Colima runs the real Docker engine inside a small Linux VM. It is not a reimplementation. It is the same dockerd that Docker Desktop runs.

This changed everything. The file /.dockerenv exists again, because real Docker creates it. The name host.docker.internal works out of the box, because Colima maps it by default. Modern Compose features work, because we use the real Compose with a real Docker socket. And best of all: Colima pretends to be Docker Desktop for the SSH agent. It creates the same socket path, /run/host-services/ssh-auth.sock, on purpose, for compatibility. You only need one setting: forwardAgent: true.

So the migration suddenly became boring. Uninstall Docker Desktop. Run colima start. Done. No changes in the repository. No changes in scripts. This is what we wanted. Well — almost. Keep reading.

Need for speed (enter Rosetta)

There was one more problem. Our main PHP image exists only for amd64. Our Macs have Apple Silicon chips. So the image must be translated. Colima’s default settings are safe but slow. The VM itself is fine — Apple’s own virtualization and fast file sharing are on by default. But Rosetta is not, so every amd64 binary crawls through QEMU’s emulation. The first boot was painful. Simple page loads took seconds. Sometimes more.

The fix was a few lines in the Colima profile config (~/.colima/default/colima.yaml):

vmType: vz # Apple's Virtualization.framework (the default — keep it explicit)
mountType: virtiofs # fast file sharing (also the default)
rosetta: true # the real fix: translate amd64 with Rosetta 2, not QEMU emulation
forwardAgent: true # the SSH agent socket from chapter 3

With Rosetta on, the amd64 PHP-FPM container ran almost as fast as a native one. The worktree stacks came up. The tests ran. For a moment, the migration looked finished.

It was not finished.

The silent killer

After some real use, php-fpm started to crash. The container would start, live for one or two seconds, and die. The exit code was 139 , which means SIGSEGV. There was no error message. No log line. No core dump. Just a dead container.

The strange part was this: some things worked, and some did not. The PHP CLI was fine: php -v, php -m, even our full unit test suite — over six thousand tests, all green. Only the FPM master process died. Always a second after start. Always silent.

The asymmetry has a boring explanation, and it is worth knowing because it sends you looking in the wrong place for an hour: opcache.enable_cli is 0 by default. The CLI never builds the shared memory segment at all, so it never touches the thing that kills FPM. Six thousand green tests told me nothing.

We made a small reproduction, to be sure it was not our app:

docker run --rm --platform linux/amd64 OUR_PHP_IMAGE php-fpm -t
# => exit code 139. Silence.

A clean image, one config test command, one crash. So the problem was below our code.

Same engine. Same Mac. Different crash.

Now here is the thing that made no sense. Docker Desktop and Colima both run the real dockerd. Both translate amd64 through the same Rosetta 2 on the same Mac. The exact same image worked on Docker Desktop for months. No crashes. Ever.

So if the engine is the same, and the translator is the same, then the difference must be somewhere lower. In the VM. Or in the way Rosetta is connected to the VM. This was the clue that later solved everything. But we did not know that yet.

Detective work

Time for the oldest debugging method: turn things off, one by one, until the problem goes away. It was the only method available, by the way — strace does not work under Rosetta, so there was no syscall trace to read. That is a large part of why this took a day. PHP makes bisection easy, though:

php-fpm -n -t # no php.ini at all => OK
php-fpm -t -d opcache.enable=0 # all, but OPcache off => OK
php-fpm -t # full config => 139

So the problem was OPcache. But not the JIT part — our image already has opcache.jit=disable. The crash happens when OPcache creates its shared memory segment. OPcache maps this memory as executable, using the mmap syscall.

And then came the first real clue. We forced OPcache to use System V shared memory (shmget) instead of mmap. The crash was gone. Even on the completely stock PHP image, with no other changes. Same PHP code. Same Rosetta. Different kernel mechanism. So the problem was not “executable memory under Rosetta” in general. It was something specific about that one mmap call.

It worked on Docker Desktop. It should work here

At this point, I had a working workaround. I could stop. Ship the SHM change, go home, be happy.

But it bothered me. Docker Desktop runs the same Rosetta 2 on the same Mac, and it never crashed. Bugs in emulation are not random. When a low-level feature misbehaves, it is usually not an accident. Usually someone made a trade-off on purpose. Often for speed. I wanted to know who, and where, and why.

The monster had a name: MAP_HUGETLB

The answer was inside PHP itself — in OPcache’s shared memory code. When OPcache starts, it asks the kernel for a block of memory. If the size happens to be a multiple of 2 MB, it tries something special: an mmap call with the flags MAP_32BIT | MAP_HUGETLB | MAP_FIXED. It wants “huge pages” — bigger memory pages that are faster for the CPU. If the kernel says no, OPcache falls back to normal memory and everything is fine. This fallback is the key to the whole story.

On our Colima VM, the Linux kernel is built with huge page support (CONFIG_HUGETLBFS=y). So the kernel does not say no right away. It starts the operation, removes the old memory at that address — and only then fails, returning ENOMEM. A correct kernel never does this: a failed mmap must leave the old memory untouched. Now the process has a hole in its memory map. Under Rosetta, that hole is not empty — translated code was living there. The process touches the hole, and it dies. SIGSEGV, one second after start, no logs. This exact non-atomic mmap behaviour is described in the Colima issue we eventually found: abiosoft/colima#1452.

And why did Docker Desktop never crash? Here I have to be honest about what I verified and what I did not. I confirmed the Colima side directly — the crash, the flag, the fallback, the fix. For Docker Desktop I only observed that the same image never crashed in months of use; the explanation that its LinuxKit kernel rejects MAP_HUGETLB early, before touching the existing mapping, is my inference, not something I traced. It fits every observation I have, but treat it as the likely story rather than a proven one.

Same engine. Same Rosetta. Different kernel behaviour for one single flag.

One more data point that supports the mechanism: the crash depends on the size of the segment, not on huge pages being available. OPcache only attempts the huge-page mapping when the segment size is a multiple of 2 MB, so opcache.memory_consumption=65 sidesteps the whole thing by never asking. And enabling huge pages properly inside the VM does not fix it either — then php-fpm hangs instead of crashing.

Two rules to fix it all

Once you see it, the fix is elegant. We cannot rebuild the VM kernel. But we can make it answer “no” to huge-page mmap calls — the same clean “no” that Docker Desktop gives. Docker has a feature exactly for this: a seccomp profile , a list of rules saying which syscalls are allowed inside containers, and how.

So we took Docker’s default profile and put two rules on top of it:

if mmap is called with the huge-page flag (flags & 0x40000) → return EPERM immediately,
if mmap is called without it → allow, as usual.

Here they are, ready to paste:

{
  "names": ["mmap", "mmap2"],
  "action": "SCMP_ACT_ERRNO",
  "errnoRet": 1,
  "comment": "colima#1452: MAP_HUGETLB -> EPERM",
  "args": [{
    "index": 3,
    "value": 262144,
    "valueTwo": 262144,
    "op": "SCMP_CMP_MASKED_EQ"
  }]
},
{
  "names": ["mmap", "mmap2"],
  "action": "SCMP_ACT_ALLOW",
  "args": [{
    "index": 3,
    "value": 262144,
    "valueTwo": 0,
    "op": "SCMP_CMP_MASKED_EQ"
  }]
}

Two things are worth decoding here, because the OCI schema is not obvious. index: 3 is the fourth argument of mmap, which is flags. And for SCMP_CMP_MASKED_EQ the OCI spec uses value as the mask and valueTwo as the expected result — so the first rule reads “mask the flags with 0x40000; if what remains equals 0x40000, fail”, and the second reads “if it equals 0, allow”. 262144 is 0x40000 is MAP_HUGETLB. Rules are matched in order, first match wins, which is why the ERRNO rule has to come first.

Building the whole file is two commands — grab Docker’s default profile and prepend the rules:

curl -sL -o ~/.colima/seccomp-no-hugetlb.json \
  https://raw.githubusercontent.com/moby/moby/master/profiles/seccomp/default.json

jq '.syscalls = ([
  {"names":["mmap","mmap2"],"action":"SCMP_ACT_ERRNO","errnoRet":1,
   "args":[{"index":3,"value":262144,"valueTwo":262144,"op":"SCMP_CMP_MASKED_EQ"}]},
  {"names":["mmap","mmap2"],"action":"SCMP_ACT_ALLOW",
   "args":[{"index":3,"value":262144,"valueTwo":0,"op":"SCMP_CMP_MASKED_EQ"}]}
] + .syscalls)' ~/.colima/seccomp-no-hugetlb.json > /tmp/p.json \
  && mv /tmp/p.json ~/.colima/seccomp-no-hugetlb.json

Then tell Colima to use it as the default profile for every container. Two things in ~/.colima/default/colima.yaml:

docker:
  seccomp-profile: /etc/docker/seccomp-no-hugetlb.json
provision:
  - mode: system
    script: |
      cp /Users/<your-username>/.colima/seccomp-no-hugetlb.json /etc/docker/

That path has to be spelled out in full. The provision script runs as root inside the VM, where $HOME is /root — but your macOS home directory is mounted at the same path it has on the host, so /Users/you/... is what resolves. Substitute your own username.

One colima restart later, check it with the same command that started the whole investigation:

docker run --rm --platform linux/amd64 YOUR_PHP_IMAGE php-fpm -t
# => "configuration file /usr/local/etc/php-fpm.conf test is successful", exit 0

Everything works on the stock image. OPcache on. Default memory model. No ini files, no per-repo overrides. And because the fix lives in the VM and not in the repository, every new Git worktree works out of the box — no more silent crashes for the next person on the team.

One caveat before you copy this: the profile is the daemon default, so it applies to every container on that machine , not just PHP. Anything that genuinely wants huge pages — a database tuned for them, a JVM started with -XX:+UseLargePages — will now get a silent EPERM and quietly fall back. For a development machine that is a trade I will take without thinking. For anything resembling production, do not paste this without knowing what else runs there.

Notes for the next traveller

Most migration stories end with “and then it worked”. This one ended inside the syscall table. Someone else will hit this: they will see a silent exit 139 and they will have no idea where to start. So I left a comment with the root cause and the seccomp workaround in the GitHub thread that describes this bug: abiosoft/colima#1452. Maybe it saves someone a Friday afternoon.

If you just want the crash to stop and you do not care why, there are three smaller escape hatches, in rising order of how much they cost you:

opcache.memory_consumption=65 — not a multiple of 2 MB, so OPcache never asks for huge pages. One line, keeps OPcache and the default memory model.
opcache.preferred_memory_model=shm — switches to System V shared memory and avoids the mmap path entirely. This is the fallback I would use if the seccomp profile ever breaks.
rosetta: false — back to QEMU. Nothing crashes, and everything is slow again.

What does not help, in case you are about to try: JIT settings, vm.overcommit_memory, ASLR, or enabling huge pages inside the VM. That last one is a trap — php-fpm stops crashing and starts hanging instead.

Was it worth it?

Honest answer: I do not know. The migration took me a full day, not the calm afternoon I hoped for. Maybe fixing our scripts for Podman would have been faster — those problems are annoying, but at least you can see them. A silent segfault inside a VM is a different kind of enemy. And the big question is still open: as a team, we have not decided yet. At first, Colima looked like the option with fewer problems. Then PHP started dying, and the fix was a custom seccomp profile. Both roads have holes. You only choose which holes you prefer.

Note, added later: I said “maybe Podman would have been faster.” I was wrong. I got curious and tested it myself. Podman does not use Rosetta by default — it is off, and being removed step by step. Without Rosetta, Podman uses QEMU instead, and that crashes too — but earlier and differently, with qemu-x86_64-static: QEMU internal SIGSEGV, before PHP even runs. This is a known, reported bug (containers/podman#22714), not something wrong with my machine. When I turned Rosetta on by hand, PHP did start, but then hit the same kind of crash as Colima — exit 139, same signal. My seccomp fix did not stop it either — this crash comes from a different syscall (munmap, not mmap with huge pages), later, when PHP shuts down. So Podman was not the easier road after all. Both of its emulation paths — QEMU and Rosetta — have their own version of this problem.

Minimal repro, both platforms:

Colima (needs rosetta: true in colima.yaml, see above):

colima start
docker run --rm --platform=linux/amd64 php:8.3-cli-bookworm \
  php -d opcache.enable_cli=1 -d opcache.enable=1 -d opcache.memory_consumption=128 -r 'echo "ok\n";'
# => exit 139, after printing "ok"

Podman (Rosetta is off by default, you must turn it on by hand):

mkdir -p ~/.config/containers
cat > ~/.config/containers/containers.conf <<'EOF'
[machine]
provider = "applehv"
rosetta = true
EOF
podman machine init --now

podman run --rm --platform=linux/amd64 php:8.3-cli-bookworm \
  php -d opcache.enable_cli=1 -d opcache.enable=1 -d opcache.memory_consumption=128 -r 'echo "ok\n";'
# => exit 139, after printing "ok"

Same flag (opcache.memory_consumption=128, a multiple of 2 MB). Same result. Two different paths to the same family of bug.

One more thing: I tested opcache.preferred_memory_model=shm on Podman under both emulation paths — Rosetta and QEMU. It fixed both. Clean runs, no crash, either way. So shm is not just a Colima trick — it works everywhere I tested it. If you want one fix that works regardless of platform, use shm, not the seccomp profile.

For now, my machine runs Colima, OPcache is on, and the Docker invoice will never come. The rest — the final team decision — is still an open question. Maybe that will be another article.