Diagnosing Xdebug Connection Failures in Local Environments
The error message Xdebug: [Step Debug] Time-out connecting to debugging client, waited: 200 ms is one of the most common friction points when setting up a local development workflow with PHP. It indicates a fundamental handshake failure: the PHP process (the server) has spun up its debugger listener, but the IDE (the client) never initiated a connection request on the expected port.
In your specific case, you have correctly configured the port mismatch by moving from the legacy 9000 to the modern standard of 9003. You have set xdebug.remote_port = 9003 in php.ini and matched it in your VS Code launch.json. Despite these settings aligning, the debugger remains unresponsive. This suggests the issue lies not in the port number itself, but in how the PHP process determines when to start listening or how the client initiates the handshake.
The Autostart Mismatch
The most frequent cause of this timeout is a discrepancy between xdebug.remote_autostart and the actual launch configuration of your web server or CLI tool.
You have enabled xdebug.remote_autostart = on. This setting tells Xdebug to automatically start debugging whenever any request hits the PHP process, assuming the client connects immediately. However, VS Code's "Listen for XDebug" mode does not connect automatically upon page load. It waits for a specific trigger or relies on the xdebug.client_host and xdebug.client_port environment variables being set in the context of the running PHP process to initiate the handshake.
When you run Apache via XAMPP, it often loads your php.ini from the installation directory rather than a custom configuration file placed in your project root. If your apache2.conf or httpd-vhosts.conf does not explicitly include the path to your custom php.ini, the settings there might be overridden by system defaults which could have remote_enable set to 0 or an outdated port.
To resolve this, verify that the PHP process you are debugging is actually loading your modified configuration. You can do this by creating a file named info.php in your project root with the following content:
<?php phpinfo(); ?>
Navigate to this URL in your browser (e.g., http://localhost/online-store/info.php). Search the output for "Xdebug". Look specifically for these lines:
- Xdebug Mode: Should say
debug. - xdebug.client_host: Should be
127.0.0.1or your specific IP. - xdebug.client_port: Should be
9003.
If the port shown in the phpinfo() output differs from 9003, your PHP process is not reading the php.ini file you edited, or it is using a fallback configuration. You may need to explicitly define xdebug.remote_host and xdebug.remote_port within the specific php.ini that Apache loads, rather than relying on global defaults.
Environment Variable Overrides
Xdebug prioritizes environment variables over php.ini directives when determining connection parameters. If your development environment sets XDEBUG_CONFIG, it can override settings defined in php.ini.
Check your system environment or your .env file (if using a framework that exports env vars to PHP) for lines like:
XDEBUG_CONFIG=client_host=127.0.0.1,client_port=9003
If you have these variables set inconsistently across different machines or shells, they can break the handshake even if your php.ini looks correct. Ensure that any environment variables match the launch.json port exactly.
Client-Side Launch Configuration
Your launch.json configuration is currently minimal. While it defines a "Listen for XDebug" profile, it lacks the explicit instruction to wait for the debugger or handle the connection timeout gracefully. The default behavior in recent VS Code versions requires the xdebug.client_host and xdebug.client_port to be explicitly passed as environment variables when launching the PHP process, not just defined in php.ini.
Update your launch.json to include the environment variable block:
{
"name": "Listen for XDebug",
"type": "php",
"request": "launch",
"port": 9003,
"pathMappings": {
"${workspaceFolder}": "${workspaceFolder}"
},
"env": {
"XDEBUG_CONFIG": "client_host=127.0.0.1,client_port=9003"
}
}
By adding the env block, you ensure that when VS Code launches the PHP script (or connects to the Apache process via specific debugging extensions), it explicitly tells Xdebug where to listen. This is often more reliable than relying solely on php.ini, as it guarantees the handshake parameters are present in the immediate execution context.
Verifying the Handshake
If the configuration changes above do not resolve the timeout, check your Xdebug log file located at c:/xampp/tmp/xdebug.log. The error message you provided is a generic notice from the PHP process indicating it gave up waiting for the client. The log will often contain more verbose details about why the connection was rejected or if the remote server refused the TCP handshake.
Ensure that no firewall on your local machine is blocking incoming connections on port 9003 (though this is rare in localhost scenarios, it happens with Docker networks or specific host configurations). Finally, remember that Xdebug 3.x requires a slightly different approach than Xdebug 2.x regarding autostart and remote mode, ensuring you are using the version of Xdebug compatible with your PHP runtime to avoid deprecated directive warnings that might mask connection errors.