PHP error guide

Xdebug legacy port 9000 mismatch: meaning and fix

warning server Affects: Xdebug 3.x except the nesting-level legacy page Last verified:

Error summary

Configure both Xdebug and the IDE on the same deliberate port. An Xdebug 2-era port remains configured while the IDE listens on Xdebug 3 default 9003.

What it means

Configure both Xdebug and the IDE on the same deliberate port. An Xdebug 2-era port remains configured while the IDE listens on Xdebug 3 default 9003.

What the error means

This message means that an Xdebug 2-era port remains configured while the IDE listens on Xdebug 3 default 9003. The exact signature distinguishes xdebug legacy port 9000 mismatch from a generic application failure.

Why PHP produces it

The engine or service reports “Xdebug legacy port 9000 mismatch” because its required precondition was not met. Configure both Xdebug and the IDE on the same deliberate port.

PHP version notes

The xdebug legacy port 9000 mismatch wording here is based on Xdebug 3.x except the nesting-level legacy page; punctuation and exception class names can differ on older branches or vendor builds.

Most common causes

  • The immediate input or configuration reaches the specific condition: an Xdebug 2-era port remains configured while the IDE listens on Xdebug 3 default 9003
  • The code path assumes the prerequisite for xdebug legacy port 9000 mismatch has already been satisfied.
  • For xdebug legacy port 9000 mismatch, development and production differ in version, extension, permissions, paths, or service configuration.
  • An earlier operation returned an unchecked value that is consumed by the line reporting xdebug legacy port 9000 mismatch.

Minimal examples

BAD — reproduces the problem

ini 
xdebug.remote_port=9000

FIXED — safer pattern

ini 
xdebug.client_port=9003

Step-by-step diagnosis

  1. Copy the complete “Xdebug: [Step Debug] Could not connect to debugging client. Tried: 127.0.0.1:9000” text and retain the first application stack frame.
  2. Reproduce xdebug legacy port 9000 mismatch in the same SAPI and environment listed for this page.
  3. Before changing xdebug legacy port 9000 mismatch, inspect the preceding value or directive and verify its type, path, version, and permissions.
  4. Apply the narrow correction—configure both Xdebug and the IDE on the same deliberate port—then repeat the original request once.

Fixes

Correct the failing prerequisite

Configure both Xdebug and the IDE on the same deliberate port

ini 
xdebug.client_port=9003

Fail explicitly at the boundary

Validate the condition before the operation that emits xdebug legacy port 9000 mismatch, and log a safe diagnostic without credentials or full production paths.

Common mistakes when fixing it

  • Suppressing xdebug legacy port 9000 mismatch instead of correcting its upstream condition.
  • Testing xdebug legacy port 9000 mismatch only with the CLI binary when the failing request runs under FPM or Apache.
  • Changing a global setting for xdebug legacy port 9000 mismatch before confirming the site-specific effective configuration.

How to prevent it

  • Add a focused test that exercises the boundary responsible for xdebug legacy port 9000 mismatch.
  • Keep runtime versions, extensions, configuration, and deploy artifacts affecting xdebug legacy port 9000 mismatch reproducible.
  • Validate external data and service return values before they can trigger xdebug legacy port 9000 mismatch.

Web server / environment notes

fpm, cli, docker, linux. The failure occurs where an Xdebug 2-era port remains configured while the IDE listens on Xdebug 3 default 9003

Tags: fpm,cli,docker,linux

Categories

Relevant ZendStudio.net tools