Fixing Xdebug with wp-env on Rootless Docker in Linux

Fixing Xdebug with wp-env on Rootless Docker in Linux

Setting up Xdebug with wp-env should take about two minutes. On my Linux machine it took a lot longer, and the root cause had nothing to do with PHP or WordPress. This is the story of fixing Xdebug with wp-env on Rootless Docker in Linux and the one-line fix that finally made my breakpoints work.

1. The Problem: Breakpoints That Never Hit

My setup was simple: Debian 13, wp-env for the local WordPress environment, and Antigravity IDE (a VS Code-based editor) with the PHP Debug extension. I started the environment with wp-env start --xdebug, launched the Listen for Xdebug configuration on port 9003, set a breakpoint, and loaded a page.

Nothing happened. The page loaded normally and the breakpoint didn’t work. The only clue was in the WordPress container logs:

Xdebug: [Step Debug] Could not connect to debugging client.
Tried: host.docker.internal:9003 (through xdebug.client_host/xdebug.client_port).

The message is clear about what failed: Xdebug lives inside the container, it tried to open a connection back to my IDE, and the connection never happened. The real question was why.

2. Finding the Root Cause

The goal was to split the problem in two: is my IDE listening correctly, and can the container actually reach it? Each test ruled out one layer.

Test 1: Is the IDE listening? On the host, while the debugger was running:

$ ss -ltnp | grep 9003
LISTEN 0 511 0.0.0.0:9003 0.0.0.0:* users:(("antigravity-ide",...))

The editor was listening on 0.0.0.0:9003, meaning all interfaces. The IDE was fine.

Test 2: Is a firewall in the way? The machine had no firewall installed, so I crossed that off the list.

Test 3: Can the container connect to the port? I ran a raw TCP test from inside the WordPress container:

$ npx wp-env run wordpress bash -c 'getent hosts host.docker.internal; timeout 3 bash -c "echo > /dev/tcp/host.docker.internal/9003" && echo OPEN || echo BLOCKED'

172.17.0.1      host.docker.internal
bash: connect: Connection refused
bash: line 1: /dev/tcp/host.docker.internal/9003: Connection refused
BLOCKED

Two details mattered here:

  • The name resolved: host.docker.internal pointed to 172.17.0.1, the usual Docker bridge gateway. So DNS was not the issue.
  • The error was “refused”, not a timeout: a firewall would normally drop packets and make the connection hang. A refusal meant something answered and said that nothing was listening at that address.

Test 4: Does that bridge even exist? 172.17.0.1 should be the docker0 interface on the host:

$ ip addr show docker0
Device "docker0" does not exist.

That was the clue. There was no docker0, and no Docker-related interface at all in ip addr. A check of docker info showed why:

$ docker info | grep -i rootless
  rootless

My Docker was running in rootless mode.

3. The First Attempt: phpConfig

Rootless Docker explains everything. In this mode the daemon and every container run inside their own network namespace, so the bridge at 172.17.0.1 lives inside that namespace. It is not my machine. Xdebug was knocking on a door in a building where my IDE doesn’t live, which is the reason of the “refused” answer.

The fix is to give Xdebug an address that points to the real host. Since my IDE listens on 0.0.0.0, my machine’s LAN IP works:

$ ip -4 route get 1.1.1.1 | awk '{print $7; exit}'

The natural place to set it is the wp-env configuration. I tried a .wp-env.override.json like this:

{
  "phpConfig": {
    "xdebug.client_host": "192.168.1.50"
  }
}

It failed immediately:

"phpConfig" is not a configuration option

Why it doesn’t work for me: the option is not recognized by the version of @wordpress/env I have installed, so its schema validation rejects it. Upgrading wp-env may be an option, but I wanted a fix that worked with the tooling I already had.

4. The Solution: .htaccess

The official wordpress Docker image runs PHP as an Apache module (mod_php). That means PHP settings that can be changed per directory can be set from an .htaccess file, and xdebug.client_host is one of them. My htacces file was already mapped into the container, so I added this at the top of the file, above the # BEGIN WordPress block (WordPress rewrites that section, so don’t put it inside):

<IfModule mod_php.c>
  php_value xdebug.client_host 192.168.1.50
</IfModule>

Swap in your own host IP. No restart is needed, because Apache reads .htaccess on every request. I reloaded the page and the debugger finally connected.

The Caveat: a LAN IP changes when your network or DHCP lease does. A better solution would use an stable address so no changes are required if the LAN IP changes. This is a simple and fast solution for fixing Xdebug with wp-env on Rootless Docker in Linux.