If you find Xdebug useful, please consider supporting the project.

Description of errors

This section lists all errors that show up in the PHP and diagnostic logs.

Configuration #

CFG-C-CHANGED

The Xdebug setting that you are trying to configure has been removed from Xdebug 3.

Some settings have been removed between Xdebug 2 and 3, and this was one of them. Please refer to the upgrade guide's section on Changed Configuration Settings on possible alternative ways of configuring this specific feature.

CFG-C-ENVMODE

The XDEBUG_MODE environment variable contains a mode that Xdebug does not support.

The XDEBUG_MODE environment variable can be used to override the mode as set with xdebug.mode. One of the modes that you are trying to enable is not supported by Xdebug.

The available modes are documented for the xdebug.mode setting. Change the contents of the XDEBUG_MODE environment variable to only include mode names that are documented.

CFG-C-MODE

The xdebug.mode setting contains a mode that Xdebug does not support.

One of the modes that you are trying to enable with the xdebug.mode setting is not supported by Xdebug. Change the value of xdebug.mode to only include modes that are documented.

CFG-W-NOZLIB

The xdebug.use_compression setting is set to true, but support for zlib compressed files is not enabled in your build of Xdebug.

Zlib compression needs to be enabled when Xdebug is compiled. Without any compile flags, the ./configure build script will enable zlib compression as long as that library and its development headers are installed. If they are not installed, or can't be found, then zlib compression will not be available.

If zlib compression is enabled, then the xdebug.use_compression setting defaults to true, and if it is not enabled, the setting defaults to false.

If zlib compression is not enabled, and you set xdebug.use_compression to true, then you will get this warning when Xdebug tries to create a compressed trace or profiling file.

Suggested solutions:

  • Turn off the xdebug.use_compression setting. This will remove the warning, and the same behaviour remains: Xdebug will create uncompressed trace files and profiling files.
  • Recompile Xdebug with the --with-xdebug-compression flag, making sure that zlib and its development header files are installed on your system. On Ubuntu/Debian this is the zlib1g-dev package, and on RedHat/Fedora you need to install the zlib-devel package.

CFG-C-REMOVED

The Xdebug setting that you are trying to configure has been removed from Xdebug 3.

Some settings have been removed between Xdebug 2 and 3, and this was one of them. Please refer to the upgrade guide's section on Changed Configuration Settings to find out the reason why this setting was removed.

CFG-W-TRGSEC-MNO

Xdebug is configured to only activate when one of the specific trigger values is present, which matches an entry which is configured through xdebug.trigger_value. Your trigger value did not match one of these values.

Xdebug's xdebug.trigger_value setting can be used to restrict which GET, POST, and COOKIE value(s) will activate features. You can use this to only allow authorised people to initiate a debugging session, or create a profiling file. In this case, a xdebug.trigger_value has been configured, but the value that you used for an XDEBUG_SESSION_START GET or POST value, or an XDEBUG_SESSION COOKIE value (also used by the browser extensions) did not match one of the configured values.

Suggested solutions:

CFG-W-TRGSEC-NO

Xdebug is configured to only activate when specific trigger value is present which matches what is configured with xdebug.trigger_value. Your trigger value did not match.

Xdebug's xdebug.trigger_value setting can be used to restrict which GET, POST, and COOKIE value(s) will activate features. You can use this to only allow authorised people to initiate a debugging session, or create a profiling file. In this case, a xdebug.trigger_value has been configured, but the value that you used for an XDEBUG_SESSION_START GET or POST value, or an XDEBUG_SESSION COOKIE value (also used by the browser extensions) did not match this value.

Suggested solutions:

CFG-W-ZLIB-A

The xdebug.profiler_append and xdebug.use_compression settings are both enabled.

Zlib compressed files don't support updates, so they can not be appended to. With both these settings enabled, Xdebug will ignore the xdebug.use_compression setting, and instead create a new uncompressed profiling file, or append to an already existing uncompressed profiling file.

Suggested solutions:

  • Turn off the xdebug.use_compression setting. This will remove the warning, and the same behaviour remains: Xdebug is appending to uncompressed profiling files.
  • Turn off the xdebug.profiler_append setting. This means that Xdebug will overwrite already existing profiling files with the same name.

Debugger

DBG-E-NOCON

Occurs when Xdebug is trying to connect to a debuging client to start a debugging session.

The debugger could not make a connection to the client. The error message indicates which host and port combinations were tried, and through which configuration options it came to that conclusion.

An example:

Could not connect to debugging client. Tried: ::1:9003 (from REMOTE_ADDR HTTP header), localhost:9003 (fallback through xdebug.client_host/xdebug.client_port)

This message indicates that Xdebug first tried to use ::1:9003 (IPv6's localhost) from the REMOTE_ADDR header, and then it fell back to localhost:9003 as configured with xdebug.client_host and xdebug.client_port.

Suggested solutions:

  • Check whether your debugging client is listening on the indicated address and port. On Linux and OSX, you can use netstat -a -n | grep LISTEN to check.
  • Change xdebug.client_host and/or xdebug.client_port to the right address/hostname and port of where the debugging client is listening.

DBG-E-NOPERM

Occurs when Xdebug has no permissions creating a connection to the debugging client.

This can happen because system configuration, such as SELinux, disallows a connection from being created.

Suggested solutions if SELinux is enabled:

  • Set SELinux to permissive mode, by changing SELINUX=enforcing to SELINUX=permissive in /etc/selinux/config, and rebooting your machine.
  • Allow httpd to make outwards connections by running: setsebool -P httpd_can_network_connect on

DBG-E-SES-INIT

Occurs when Xdebug succesfully connected to a debugging client, but something went wrong sending the first data packet.

This can happen if the socket that Xdebug connected to does not have a debugging client listening on it. For example, when it is PHP-FPM instead. Check that the port that PHP-FPM uses is not the same as the one that Xdebug uses. By default, they both use port 9003.

Suggested solution:

  • Configure PHP-FPM to use a different port than 9003, or a Unix domain socket instead.
  • Use xdebug.client_port and your debugging client's configuration to change the debugging port to a different value (such as 9007).

DBG-E-TIMEOUT

Occurs when Xdebug connection attempt times out.

This can happen because no debugging client is listenting, a firewall prevents the connection by silently dropping connections, or when the latency is too high.

Suggested solution:

  • Check whether a firewall is active, and if it is silently dropping connection attempts from Xdebug to the debugging client.
  • Check whether your debugging client is listening on the address and port as indicated in the error message.
  • Use xdebug.connect_timeout_ms to increase the time-out value itself. A reasonable value for a time-out is anywhere from 200 to 2000 milliseconds.

DBG-W-BRKFILE

Occurs when the IDE tries to set a breakpoint in in a file that not exist on the filesystem.

The likely reason for this to happen is that the IDE debug configuration does not have path mappings set up, or correctly set up. Path mappings are needed to map filenames as Xdebug seems them on a remote host, to filenames as the IDE sees them on the local host. Without a path mapping, the IDE can not translate to the filename that Xdebug requires for setting a breakpoint.

Suggested solutions:

  • PhpStorm: Follow the instructions on how to set up path mappings.
  • Visual Studio Code: Refer to the paragraph on pathMappings in the Remote Host Debugging section.

DBG-W-CON

Occurs when xdebug.discover_client_host is turned on, and Xdebug could not connect to the client with an address found in the HTTP headers.

This can occur when networking is not correctly set up, or Vagrant and Docker networks are not configured correctly. Connecting back to the address of the machine where the debugging client runs only works if they are on the same network. If a networking set-up makes this impossible, then you can not use xdebug.discover_client_host.

If the address found in the HTTP headers can not be contacted, Xdebug falls back to the static address as configured by xdebug.client_host.

Suggested solutions:

  • Set xdebug.discover_client_host to 0 and configure a static address with xdebug.client_host.
  • If a debugging connection is working, ignore the warning or set xdebug.discover_client_host to 0.
  • Check your networking set up so that the web server sees the HTTP request coming from an IP address on the same network as where the debugging client is listening. For example, you can check the latter on a Unix platform by running ifconfig and see if the IP address matches with what is sent in the HTTP headers.

DBG-W-DETACH

Xdebug succesfully connected to an IDE or Xdebug Cloud, but the IDE or Xdebug Cloud aborted the debugging session with the detach protocol command.

IDEs can detach for several reasons:

  • The IDE can detach when it can not relate the incoming request and associated file name with its path mappings.
  • The IDE chooses to ignore the request on your behalf, through a dialog.
  • The IDE chooses to ignore the request for other reasons.
  • You can instruct the IDE to stop debugging, and let the application running.

Suggested solutions:

  • Set up the right path mappings for your IDE.
  • Don't choose to ignore the incoming debugging session when the IDE asks.

Xdebug Cloud uses detach when the Cloud ID is not existing, or when no IDE is connected for the Cloud ID. A message with the exact reason Diagnostics Log that is part of xdebug_info()'s output.

Suggested solutions:

  • Check whether the Cloud ID as configured in Xdebug with xdebug.cloud_id matches the one set in your IDE.
  • Check your Xdebug Cloud profile page to see if you have used an available token.

DBG-W-HDR

Occurs when Xdebug's xdebug.discover_client_host setting is configured, and no header could be found to use for information about which host to connect to.

If Xdebug can not find a header containing this information, it will fall back to address configured through xdebug.client_host. If a debugging connection is succesfully created with that method, you can ignore this warning.

Suggested solutions:

  • If a debugging connection was succesfully made, set xdebug.discover_client_host to 0.
  • If you are running Xdebug on the command line, then no HTTP headers can be present. Set xdebug.discover_client_host to 0, or just ignore the warning.
  • Use your brower's debugging tools to see which HTTP headers were sent to the HTTP server. If none were sent, then it is possible that a proxy server or Web server configuration stripped out the header(s). This is unlikely, as at least the REMOTE_ADDR HTTP header should always be present.
  • If using xdebug.discover_client_header, check if you have not made a typo in your header's name.

DBG-W-INVADDR

Occurs when Xdebug's xdebug.discover_client_host setting is configured, and while trying to find which host to connect to, finds an address containing ://.

This warning indicates that an invalid header was present, perhaps maliciously.

Suggested solution:

  • Use your brower's debugging tools to see which HTTP headers were sent to Xdebug, and find out which one contains ://. Then make sure that header is either not sent, or disable xdebug.discover_client_host.

DBG-W-REMCLOSE

Occurs when Xdebug is sending data to a debugging client, but the debugging client has closed the connection.

Indicates that the debugging client has closed the debugging connection and Xdebug was not aware of this. When this warning happens, the debugging connection is aborted on the Xdebug side too, and the rest of the request can not be debugged.

DBG-W-OPCACHE

Occurs when the debugger detects that Zend OPcache is loaded after Xdebug as Zend extension.

This is problematic, as both Xdebug and OPcache insert handlers into PHP's execution pipeline. If OPcache is loaded after Xdebug, it installs its own handler, which then has the possibility to prevent Xdebug from doing work.

This problem does not occur if Xdebug is loaded after OPcache, because Xdebug does not prevent other extensions from doing their work.

You can verify the loading order by searching for the "Zend Scripting Language Engine" section in phpinfo() output. It is next to the Zend Engine logo. The following shows the wrong loading order, because Zend OPcache follows Xdebug: 

This program makes use of the Zend Scripting Language Engine:
Zend Engine v4.1.21, Copyright (c) Zend Technologies
    with Xdebug v3.2.3, Copyright (c) 2002-2023, by Derick Rethans
    with Zend OPcache v8.1.21, Copyright (c), by Zend Technologies

Suggested solutions:

  • Change the order in which INI files are loaded so that the one for Xdebug sorts later than OPcache.

    You can find which INI files are loaded in phpinfo() output behind "Loaded Configuration File" and "Additional .ini files parsed".

    This is an example of how this should look like, with 99-xdebug.ini sorting after 20-opcache.ini: 

Configuration File (php.ini) Path:       /usr/local/php/lib
Loaded Configuration File:               /usr/local/php/lib/php.ini
Scan this dir for additional .ini files: /usr/local/php/lib/conf.d
Additional .ini files parsed:            /usr/local/php/lib/conf.d/20-mongodb.ini,
                                         /usr/local/php/lib/conf.d/20-opcache.ini,
                                         /usr/local/php/lib/conf.d/99-xdebug.ini

  • Stop OPcache from loading, by removing the zend_extension=opcache line from all INI files that are loaded, or by removing a 20-opcache.ini file or similar, if it exists.
  • Disable OPcache, by setting opcache.enable=0 in any INI file.

Once you have made the necessary changes, and restarted your webserver, or PHP-FPM processes, the correct order should look like this: 

This program makes use of the Zend Scripting Language Engine:
Zend Engine v4.1.21, Copyright (c) Zend Technologies
    with Zend OPcache v8.1.21, Copyright (c), by Zend Technologies
    with Xdebug v3.2.3, Copyright (c) 2002-2023, by Derick Rethans
DBG-W-SENDERR

Occurs when Xdebug is sending data to a debugging client, but it could not send all, or any data.

This could indicate that the debugging client has closed the debugging connection, or that an interrupt interrupted the transmission of the full packet of data. This is not something that Xdebug can recover from, and the debugging connection will be in an unstable state. The rest of the request can not be debugged.

DBG-W-SOCK1

Occurs when Xdebug is trying to connect to a debuging client to start a debugging session.

Indicates that Xdebug had an issue obtaining information about the configured hostname or IP address from the Operating System. This can indicate an issue with an entry in the /etc/hosts file or an issue with reaching a DNS server.

DBG-W-SOCK2

Occurs when Xdebug is trying to connect to a debuging client to start a debugging session.

Indicates that Xdebug could not create a socket to connect to a debugging client.

DBG-W-SOCK3

Occurs when Xdebug is trying to connect to a debuging client to start a debugging session.

Indicates that Xdebug could not set an option on the socket, such as preventing the inheritance of a socket by client processes, setting the socket in non-blocking mode, or setting the "no delay" option.

DBG-W-SOCK4

Occurs when Xdebug is trying to connect to a debuging client to start a debugging session.

A transient error saying that although a socket was created, it not immediately was ready for handling communications. This can be safely ignored.

DBG-W-UNIX

Occurs when xdebug.client_host starts with unix:// and something went wrong.

Xdebug could not create a Unix domain socket, connect to the created Unix domain socket, or prevent the created socket from being inherited by forked processes. The error message will indicate the reason that the operating system gave.

A list of possible reasons:

  • connect: No such file or directory: The path that you are trying to use does not exist, or you have no permission to write to it.
  • connect: Connection refused: The file name that you specified is not a Unix domain socket. For example, a normal file with that name already exists.

Suggested solutions:

  • Check whether the path after the initial unix:// exists, is not a normal file, and con be written to by the Operating System users under which PHP and Xdebug run. Please note that this needs to be a fully qualified path, so unix:///tmp/xdebug.socket and not unix://tmp/xdebug.socket.
  • Switch to a non-Unix domain socket value by setting xdebug.client_host to an IP address or hostname instead.

DBG-W-UNIX-WIN

Occurs when xdebug.client_host starts with unix:// and Xdebug is running on a Windows platform.

Unix domain sockets are not supported on Windows. Please use a hostname or IP address to configure the step debugger client address through xdebug.client_host instead.

Garbage Collection Stats

GC-E-DISABLED

Occurs when garbage collection stats is enabled, but PHP's garbage collection mechanism is turned off.

PHP's garbage collection is turned off through PHP's zend.enable_gc setting, or gc_disable() has been called in a script.

Suggested solutions:

  • Check whether zend.enable_gc is set to 0 in php.ini, and change the value to 1.
  • Check whether your script, framework, or application calls gc_disable(), and if so, remove that function call.

Logging #

LOG-E-OPEN

Occurs when Xdebug is trying to open a log file, and it can't.

It is likely that either the path configured within xdebug.log does not exist, or that Xdebug has no permissions creating or writing to the file.

Suggested solutions:

  • Check whether the directory exists, and if not, create it.
  • If the directory exists, check whether the user that Xdebug, PHP, and the web server run at, have permissions to create a file in the directory.
  • If the file exists, check whether the user that Xdebug, PHP, and the web server run at, can write to the file.

Profiling #

PROF-E-OPEN

Occurs when Xdebug is trying to create a profiling file, but it can not.

It is likely that either the path configured within xdebug.output_dir does not exist, or that Xdebug has no permissions creating or writing to the file.

Suggested solution:

PROF-W-NOTDIR

Occurs when xdebug.output_dir is not set to a directory, but a normal file.

Suggested solution:

PROF-W-PERM

Occurs when Xdebug can not create in the xdebug.output_dir directory.

Suggested solutions:

  • Change the permissions on xdebug.output_dir and parent directories so that user under which PHP and Xdebug run at has write permissions.
  • Change xdebug.output_dir to a directory to which the user that PHP and Xdebug run at has write permissions.

PROF-W-STAT

Occurs when xdebug.output_dir is not a valid path.

Suggested solution:

Tracing #

TRACE-E-OPEN

Occurs when Xdebug is trying to create a trace file, but it can not.

It is likely that either the path configured within xdebug.output_dir does not exist, or that Xdebug has no permissions creating or writing to the file.

Suggested solution:

TRACE-W-NOTDIR

Occurs when xdebug.output_dir is not set to a directory, but a normal file.

Suggested solution:

TRACE-W-PERM

Occurs when Xdebug can not create in the xdebug.output_dir directory.

Suggested solutions:

  • Change the permissions on xdebug.output_dir and parent directories so that user under which PHP and Xdebug run at has write permissions.
  • Change xdebug.output_dir to a directory to which the user that PHP and Xdebug run at has write permissions.

TRACE-W-STAT

Occurs when xdebug.output_dir is not a valid path.

Suggested solution: