Xdebug Troubleshooter

How it works

What it does

The Xdebug Troubleshooter asks focused questions about your setup—IDE listening state, Xdebug version family, trigger vs always-on, Docker vs local SAPI—and returns structured likely causes with fixes. It encodes common failure patterns instead of guessing blindly.

When to use it

• IDE shows “waiting for connection” forever
• Browser requests never start a debug session
• Only CLI debugging works but not web, or the reverse
• It works on bare metal but fails in Docker

How input is processed safely

You submit questionnaire fields and optional log snippets. The tool does not open ports to your IDE, does not SSH into your servers, and does not execute PHP. Log text is scanned for known markers only.

Examples

• Firewall/IDE not listening on 9003
• Path mapping mismatches so breakpoints never bind
• Xdebug mode not including debug
• Trigger cookie/query missing when start-upon-request is off

Common mistakes

• Assuming port 9000 still applies after upgrading to Xdebug 3 defaults
• Debugging through a CDN/cache that strips cookies
• Multiple PHP SAPIs loaded with different ini files

Most failures cluster into a few buckets: IDE not listening, wrong port, Xdebug not loaded in the SAPI you think you are hitting, network path blocked, trigger not present, or breakpoints bound to the wrong path. The troubleshooter steers you through those buckets in an order that usually saves time.

Collect evidence before changing many variables at once. Confirm phpinfo() (locally) shows Xdebug for the web SAPI, confirm IDE listen state, then test with a minimal script. Changing IDE, Docker, and ini simultaneously makes root cause harder to see.

If only one of CLI/web works, you almost certainly have divergent ini files. Fix the SAPI you actually use in the failing workflow rather than copying settings into the wrong place.

Privacy note

Logs may include file paths and query strings. Redact tokens and personal data before pasting diagnostic output.

Safety notes

• Submitted tool contents are not written to analytics or search logs.
• This site never evaluates arbitrary PHP from the browser.
• Generated configs are starting points—validate on a staging host before production.