Debugger: (php) process exited before debugger attached

[GuiEpi]

Summary

PHP Xdebug does not start with the error "process exited before debugger attached".

I'm aware of a similar issue that was closed for Python, but that error was related to "pip not installed" whereas I'm experiencing this issue with PHP.

Just for your information, xdebug works well on vscode.

Description

Steps to trigger the problem:

1. Create a debug.json with Xdebug configuration as shown in the documentation

// Project-local debug tasks
//
// For more documentation on how to configure debug tasks,
// see: https://zed.dev/docs/debugger
[
  {
    "label": "PHP: Listen to Xdebug",
    "adapter": "Xdebug",
    "request": "launch",
    "initialize_args": {
      "port": 9003
    }
  }
]

2. Start debug session

Expected Behavior:

The debug session is successfully started.

Actual Behavior:

The debug session is not started, and the following output appears in the console:

error: 
error: process exited before debugger attached.

Zed logs:

2025-10-22T14:08:40+02:00 INFO  [dap::transport] Debug adapter has connected to TCP server 127.0.0.1:33965
2025-10-22T14:08:40+02:00 ERROR [debugger_ui::debugger_panel] 
error: process exited before debugger attached.

Zed Version and System Specs

Zed: 0.208.6
OS: Ubuntu 24.04.3 LTS
Memory: 64.0 GiB
Architecture: 64-bit
CPU: Intel® Core™ i5-10210U × 8
GPU: Intel® UHD Graphics (CML GT2)

[ConradIrwin]

Thanks for reporting.

Can you connect to that port via Xdebug from the command line?

If possible, can you see the difference between how VSCode configures this and how Zed does?

[GuiEpi]

Can you connect to that port via Xdebug from the command line?

Yes, Xdebug works correctly when a listener is present.

Test performed:

# Terminal 1
nc -l 9003

# Terminal 2  
php7.2 -dxdebug.mode=debug -dxdebug.start_with_request=yes -dxdebug.client_port=9003 test.php

Result: Xdebug successfully connects and sends the DBGp handshake:

<?xml version="1.0" encoding="iso-8859-1"?>
<init xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" 
      ...
</init>

Zed behavior:

1. Start debugger in Zed => Crashes immediately with "process exited before debugger attached"
2. ss -tuln | grep 9003 => No listening socket (Zed never opens port 9003)

VSCode comparison:

Identical configuration works perfectly in VSCode. It opens the socket on port 9003 and Xdebug connects successfully.

Here is my VSCode config:

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

[Anthony-Eid]

The Zed PHP docs seem to be out of date, we no longer support initialize_args. Could you please try the below configuration to make sure it works on your end before I close the issue?

{
    "label": "PHP: Listen to Xdebug",
    "adapter": "Xdebug",
    "request": "launch",
    "port": 9003
  }

[Anthony-Eid]

Also, could you please add your DAP logs next time your debug session fails to attach? You can access them but clicking on one of the top right icons in the debug panel after the session fails.

[dahaupt]

I have the same issue using this configuration:

{
    "label": "Listen to xdebug (PHP-Zed Config)",
    "adapter": "Xdebug",
    "request": "launch",
    "pathMappings": {
      "/var/www/html": "$ZED_WORKTREE_ROOT"
    }
}

The DAP log is empty showing No adapter selected and I can't select any adapter.

[GuiEpi]

The Zed PHP docs seem to be out of date, we no longer support initialize_args. Could you please try the below configuration to make sure it works on your end before I close the issue?

{
"label": "PHP: Listen to Xdebug",
"adapter": "Xdebug",
"request": "launch",
"port": 9003
}

I try with this one and same error.

Also, could you please add your DAP logs next time your debug session fails to attach? You can access them but clicking on one of the top right icons in the debug panel after the session fails.

Like @dahaupt my DAP log is empty

[Anthony-Eid]

@GuiEpi Is there an open source PHP repo I could use to test this on? If not I could make my own repo

[GuiEpi]

@GuiEpi Is there an open source PHP repo I could use to test this on? If not I could make my own repo

I don't have one, sorry. Maybe @dahaupt does?

Alternatively, you could quickly scaffold a test project using API Platform:

1. Follow the setup: https://api-platform.com/docs/symfony/
2. Then see debugging tips: https://api-platform.com/docs/symfony/debugging/

[karatekaneen]

@Anthony-Eid I have the same issue with these settings (our repo have a bit of a strange structure)

[
  {
    "adapter": "Xdebug",
    "label": "Listen for Xdebug",
    "request": "launch",
    "port": 9003,
    "pathMappings": {
      "/var/www/html/rw": "$ZED_WORKTREE_ROOT/src",
      "/var/www/composer": "$ZED_WORKTREE_ROOT",
       "/var/www/composer/src": "$ZED_WORKTREE_ROOT/src"
    },
    "log": true
  }
]

And like the others my DAP logs are empty as well. I am running this version:

Zed 0.211.4 
62ece18dfedd5fae028c8ab10f751652b7f814e6