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.

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-CON

Occurs when xdebug.remote_connect_back 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.remote_connect_back.

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.remote_connect_back to 0 and configure a static address with xdebug.client_host.
  • If a debugging connection is working, ignore the warning or set xdebug.remote_connect_back 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-HDR

Occurs when Xdebug's xdebug.remote_connect_back 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.remote_connect_back to 0.
  • If you are running Xdebug on the command line, then no HTTP headers can be present. Set xdebug.remote_connect_back 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.remote_addr_header, check if you have not made a typo in your header's name.

DBG-W-INVADDR

Occurs when Xdebug's xdebug.remote_connect_back 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.remote_connect_back.

DBG-W-SENDERR

Occurs when Xdebug is sending data to a debugging client, but it 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-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.

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: