bin/xdebug enable shows "Invalid mode: enable" and PhpStorm does not receive debug connections

[roneclay]

Description

I followed the documentation to enable Xdebug and connect it with PhpStorm, but encountered the following issues:

1. The command bin/xdebug enable fails with the following error:
   Invalid mode: enable

Valid modes are:

off

develop

coverage

debug

gcstats

profile

trace

2. I then tried bin/xdebug debug, which worked for enabling debug mode. However, PhpStorm still doesn't receive any Xdebug connections, and breakpoints are not triggered.

This suggests:

• Either the documentation is outdated (enable is not a valid mode),
• Or something is misconfigured between the container and PhpStorm.

Steps To Reproduce

1. Clone and set up the project using markshust/docker-magento
2. Run bin/xdebug enable
   → Observe the "Invalid mode" error
3. Run bin/xdebug debug instead
4. Install Chrome Xdebug Helper and set IDE Key to PHPSTORM
5. Open PhpStorm and enable "Listen for PHP Debug Connections"
6. Try to access the Magento frontend or a PHP file and hit a breakpoint

Expected Result

• bin/xdebug enable should work as documented
• PhpStorm should receive incoming Xdebug connections
• Breakpoints should be triggered correctly

Actual Result

• bin/xdebug enable fails:
  Invalid mode: enable

• PhpStorm does not receive any Xdebug connection

• Breakpoints are not hit

Environment

• OS: macOS 15.1.1 (Build 24B91)
• Docker version: 27.4.0, build bde2b89
• PhpStorm version: 2025.1.1
• Magento version: 2.4.8
• Xdebug version in container:

php -v | grep Xdebug
  with Xdebug v3.4.1, Copyright (c) 2002–2025, by Derick Rethans

[dosubot]

Hi @roneclay! I'm Dosu and I’m helping the docker-magento team.

The error with bin/xdebug enable is expected—enable is not a valid mode for the current script. The valid modes are: off, develop, coverage, debug, gcstats, profile, and trace. To enable debugging, use bin/xdebug debug instead. The documentation you followed appears to be outdated on this point, as the official script and recent docs only reference these modes and not enable (source).

For PhpStorm not receiving Xdebug connections, here are the key configuration points to check:

• PhpStorm should listen for Xdebug on port 9003, with the hostname set to localhost.
• Path mappings must map /var/www/html (inside the container) to your local project directory.
• The Chrome Xdebug Helper should be installed and set to the IDE Key PHPSTORM.
• In PhpStorm, set the Debug Port to 9000,9003 and ensure a server is configured with your domain name, port 80, and the correct path mapping.
• Create a PHP Remote Debug configuration, filter by IDE key PHPSTORM, and ensure the Chrome Xdebug Helper is in Debug mode (bright green icon) (source).

The container’s php.ini sets xdebug.client_host = host.docker.internal and xdebug.idekey = PHPSTORM, which matches the recommended setup (source).

If breakpoints still aren’t hit, double-check that your firewall or security software isn’t blocking port 9003, and that you’re accessing the site through the domain configured in PhpStorm’s server settings. Also, make sure you’re using bin/xdebug debug before starting your debug session.

If you need a step-by-step guide for PhpStorm setup, let me know!

To reply, just mention my name @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}   

[roneclay]

@dosu,

Thanks so much for your detailed explanation and help! That cleared up the confusion about the bin/xdebug enable command, and using bin/xdebug debug worked perfectly.

Best regards,

[dosubot]

You're welcome! Happy to help!

To reply, just mention my name @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}