Trellis + Xdebug + Vscode - local development

I’ve had a hell of a time getting xdebug working locally with vscode, but now that I have, I thought I’d share.

installed this:
using chrome for debugging, and I did not install any chrome extensions

my launch.json config:

"version": "0.2.0",
"configurations": [{
 "name": "Listen for XDebug",
 "type": "php",
 "request": "launch",
 "pathMappings": {
     "/srv/www/": "${workspaceRoot}/site/web/app"
   "port": 9000
} is the site name you are using. (you might be using something like or http://example.test, but your site name would be

I’m running this launch.json from the root of my project (ie the folder that contains trellis and bedrock)

first run vagrant up then run the debugger, throw in a breakpoint, then navigate to

Hope this helps someone.


Hi @lane thanks so much for this. I have debugging set up thanks to you.

is workspaceRoot a Vscode variable?

Also, can you shed some light on the last step - visiting that url? I hadn’t realised this was needed after every vagrant up! (to anyone referencing this - if debugging has mysteriously stopped working, be sure to redo that last step!!)


Getting into this conversation a little late, but…

Thanks for your clarifications about setting up the debugging in VS Code! But I felt a bit annoyed with the need of using the ?XDEBUG_SESSION_START=XDEBUG_ECLIPSE-bit.

So I found out that by adding xdebug_remote_autostart: 1 to trellis/group_vars/development/php.yml and then running vagrant reload --provision the debug session starts automagically.
Just a tip (and maybe you, @d-a-v-e, are interested in this).

And yes @d-a-v-e workspaceRoot is a VS Code variable .


thanks for the tip @adambrgmn. This doesn’t auto start xdebug in production does it?

No it wont :slight_smile: