Extension is not working with XDebug 3.4.2 installed in Docker container

[balda38]

PHP version: 8.1.31
XDebug version: 3.4.2
Extension version: 1.35.0

Launch.json:

{
    "name": "Listen for XDebug on Docker",
    "type": "php",
    "request": "launch",
    "port": 9003,
    "pathMappings": {
        "/var/www/html": "${workspaceFolder}"
    },
    "xdebugSettings": {
        "max_data": -1
    }
}

XDebug config:

zend_extension = xdebug.so
xdebug.mode = debug
xdebug.start_with_request = yes
xdebug.discover_client_host = 1
xdebug.client_host = host.docker.internal
xdebug.client_port = 9003

XDebug log:

Log opened at 2025-03-25 08:23:37.457761
[33] [Config] WARN: Not setting up control socket with default value due to unavailable 'tsc' clock
[33] [Step Debug] INFO: Checking for client discovery headers: 'HTTP_X_FORWARDED_FOR,REMOTE_ADDR'.
[33] [Step Debug] INFO: Checking header 'HTTP_X_FORWARDED_FOR'.
[33] [Step Debug] INFO: Checking header 'REMOTE_ADDR'.
[33] [Step Debug] WARN: Could not discover client host through HTTP headers, connecting to configured address/port: host.docker.internal:9003.
[33] [Step Debug] INFO: Connected to debugging client: host.docker.internal:9003 (fallback through xdebug.client_host/xdebug.client_port).
[33] [Step Debug] -> <init xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" fileuri="file:///var/www/html/artisan" language="PHP" xdebug:language_version="8.1.31" protocol_version="1.0" appid="33" idekey="XDebug Docker"><engine version="3.4.2"><![CDATA[Xdebug]]></engine><author><![CDATA[Derick Rethans]]></author><url><![CDATA[https://xdebug.org]]></url><copyright><![CDATA[Copyright (c) 2002-2025 by Derick Rethans]]></copyright></init>

I can assume that everything is fine here. But every time i try to debug the code, the VS code debug console shows me the following error: "Failed initializing connection 2: connection closed (on close)" and ofc nothing happens.

I've already tried different ports (even though nothing uses 9003) and different hosts (local ip of the docker container too). But i was only able to debug the code in two cases:

• outside the container, using exactly the same config on my machine
• after manually downgrading xdebug inside the container (tested on 3.1.2)

There doesn't seem to be any breaking changes in xdebug 3.4.2 or earlier in terms of its config. Any thoughts?

[zobo]

Interesting. Just to be sure:

• VSCode runs on host (Linux?)
• PHP runs inside Docker
• File inside Docker is /var/www/html/artisan and then file mapping to ${workspaceFolder}
• Works if you downgrade Xdebug to 3.1.2. Does not work with 3.4.2 ?

I'll setup a test env and let you know.

[balda38]

@zobo thank you!

• VS Code runs on MacOS host
• correct
• right, this file is the entry point. ${workspaceFolder} matches /var/www/html inside the container
• correct

[zobo]

Have not had the time to test yes, but try one thing: max_data should be 0 for unlimited.

[zobo]

One quick note:

xdebug.discover_client_host = 1
xdebug.client_host = host.docker.internal

These two actually contradict each other. You should have one or the other. I suggest you try to put one of you host IPs into client_host and see if there's some other behavior. Also try to add xdebug_info() at the top of your script, to inspect the xdebug logs.

Now my tests.

I set up on my Linux VM as I didn't yet had time to try this on my Mac.

I isolated everything into a docker with devcontainer:

Dockerfile

FROM php:8.1.31-cli-bookworm
RUN pecl install xdebug-3.4.2 \
	&& docker-php-ext-enable xdebug

.devcontainer/devcontainer.json

{
	"name": "Existing Dockerfile",
	"build": {
		"context": "..",
		"dockerfile": "../Dockerfile"
	},
	"customizations": {
		"vscode": {
			"extensions": ["xdebug.php-debug"]
		}
	}
}

.vscode/launch.json

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for XDebug on Docker",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                // "/var/www/html": "${workspaceFolder}"
            },
            "xdebugSettings": {
                "max_data": -1
            }
        },
        {
            "name": "Launch currently open script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 0,
            "runtimeArgs": [
                "-dxdebug.start_with_request=yes"
            ],
            "env": {
                "XDEBUG_MODE": "debug,develop",
                "XDEBUG_CONFIG": "client_port=${port}"
            }
        }
       ]
}

test.php

<?php

$a = "a";
xdebug_break();
var_dump($a);

See if you can containerize your whole VSCode and if you have the same problem.

[balda38]

@zobo unfortunately, nothing helped. The same error "Failed initializing connection 2: connection closed (on close)" appears again or nothing happens at all

I'll try containerize VSCode

[balda38]

Well, the same inside the container

Launch.json:

{
    "name": "Listen for Xdebug",
    "type": "php",
    "request": "launch",
    "port": 9003
}

I always see the same error "Failed initializing connection 2: connection closed (on close)" again with XDebug 3.4.2. I tried different hosts again and nothing. But it works perfectly with XDebug 3.1.2. I didn't even change the original XDebug config

[zobo]

Do I understand correctly, that you opened the workspace with devcontainer config, so that vscode runs inside docker with php and with the default xdebug and php ini? And you then changed the Xdebug version in Dockerfile? And local Xdebug-vscode connection inside docker works for 3.1.2, but not for 3.4.2?

[balda38]

@zobo correct!

[zobo]

Try to add this to your php.ini or xdebug.ini
xdebug.control_socket=no

[balda38]

@zobo same. Tried to debug inside and outside the container

[zobo]

This is quite a mystery... How about previous Xdebug version? 3.3.2. The strange thing is, your xdebug.log says Xdebug tried to send the DBGP init packet
[33] [Step Debug] -> <init xmlns="urn:deb...

Is this still the case? This kind of looks like Xdebug is connecting to some other process, that does not understand the debug protocol...

Did you try adding xdebug_info() to the top of your php file, to see if there is something useful?

Make sure to know what IP Xdebug is trying to connect to.
Try to start the debugger (Listen for XDebug on Docker), then enter the docker with docker exec -it NAME bash and try to telnet to the IP of the IDE - the IP you see Xdebug trying.. or try to reason what the actual IP should be...