Error running script.php: Port 9000 is busy

Error running script.php: Port 9000 is busy

  1. Blog
  2. 15 November 2026
  3. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

Error running script.php: Port 9000 is busy

When you attempt to attach a PHP debugger in PhpStorm and encounter the message Error running script.php: Port 9000 is busy, the issue is almost invariably a port collision on the server side. You have correctly identified that both Xdebug and your IDE are configured to use port 9000, and netstat -na confirms that a service is already listening on that address.

This specific error indicates that Xdebug has successfully initialized and is waiting for a connection from the client (PhpStorm). However, because the port is occupied by another process or an incorrectly configured instance of Xdebug, PhpStorm cannot establish the handshake required to pause execution at your breakpoints. While changing the port to something like 10001 or a high-numbered random port often resolves the immediate error, it is generally not the ideal solution for production environments.

Understanding the Port Collision

To debug effectively, Xdebug acts as a reverse proxy for debugging sessions. It listens on a specific TCP port (defaulting to 9000) and waits for the IDE to connect. When you hit a breakpoint in PhpStorm, the IDE attempts to open a socket connection back to the server at 127.0.0.1:9000.

If netstat shows LISTEN on port 9000, but Xdebug is already reporting that it is ready (which it implies by waiting for the client), there are two common culprits:

  1. Multiple Xdebug Instances: You may have loaded the xdebug.so extension in multiple PHP-FPM pools or Apache configurations simultaneously. Each instance tries to bind to port 9000, causing a conflict.
  2. Legacy Bindings: On older systems (indicated by your path /usr/lib/php5/...), there might be a legacy Xdebug client or a different debugging tool that has claimed the port.

Why Changing the Port is Not Always Best

Your observation that changing the port to 10001 or a number above 50k works confirms that the conflict is purely numeric. However, simply picking a random high-numbered port introduces fragility into your development workflow.

According to the Xdebug documentation, port 9000 is the standard default for both the client and the bundled debug client. As many debugging clients use this port number, it is best practice to leave this setting unchanged unless you have a specific reason not to. If you arbitrarily change the server's xdebug.remote_port to 10001 without ensuring the IDE matches it exactly every time, or if you decide to switch back later, you risk breaking your debugging sessions again.

Furthermore, high-numbered ports can sometimes be restricted by firewall rules or SELinux policies depending on your OS distribution, whereas port 9000 is typically whitelisted for development tools.

The Correct Fix: Cleaning Up Configuration

Rather than treating the symptom by changing the port number indefinitely, you should aim to resolve the underlying resource conflict. This usually involves ensuring that only one instance of Xdebug is active per PHP process pool.

  1. Audit Your PHP-FPM/Apache Configurations: Check your php.ini files in multiple locations (e.g., /etc/php/5.x/fpm/php.ini, /etc/php/5.x/apache2/php.ini). Ensure that the [XDebug] section with zend_extension loaded is not duplicated across multiple pools.
  2. Verify the Extension Load: Run php -m | grep xdebug. If you see multiple entries or if the extension loads twice due to conflicting include paths, remove the duplicate configuration entries.
  3. Restart Your Web Server: After modifying php.ini or removing conflicting extensions, restart your PHP-FPM or Apache service. A mere reload might not clear the memory state where the old socket binding is stuck.

Implementation Example

If you find that the default port 9000 is indeed blocked by a legacy process and you prefer to stick with a custom port for some reason (perhaps to avoid conflicts on shared hosting or specific CI environments), ensure consistency across all configurations:

Server Side (php.ini):

[XDebug]
zend_extension="/usr/lib/php5/20090626+lfs/xdebug.so"
xdebug.remote_enable=1
xdebug.remote_port=10001
xdebug.profiler_enable_trigger=1

IDE Side (PhpStorm Settings):
Navigate to Settings | PHP | Debug and verify that the "PHP Debug Port" is explicitly set to 10001. If this matches, the handshake should succeed.

Final Considerations for Production

While running a debugger on port 9000 is standard for development, it is important to remember that Xdebug has performance implications. In a production environment, you should disable xdebug.remote_enable and xdebug.profiler_enable. Leaving these enabled in production can significantly degrade application performance due to the overhead of maintaining the debug connection and handling stack traces.

If you are using Laravel or similar frameworks where configuration is often centralized, ensure your php.ini settings align with your environment. If you encounter persistent issues on port 9000 despite cleaning configurations, switching to a non-standard port like 10001 remains a valid temporary workaround, provided the IDE and server configurations are perfectly synchronized. For more details on configuring remote debugging, refer to the official Xdebug documentation.

Our network