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

FAQ

Frequently Asked Questions

Using Xdebug

Q: phpinfo() reports that Xdebug is installed and enabled, yet I still don't get any stacktraces when an error happens.
A1: You have to search through all your PHP libraries and include files for any "set_error_handler" calls. If there are any, you have to either comment it out, or change the body of the handler function to call xdebug_* api functions.
A2: You do not have set display_errors to 1 in php.ini
Q: Xdebug doesn't format output.
A: Make sure you have PHP's html_errors set to 1 in php.ini
Q: The debug client doesn't receive any connections, what do I do wrong?
A: You probably forgot to set the environment variable or to add the necessary information to your URL. See the documentation for more information.
A: Have you checked your firewall settings? Make sure the port Xdebug is listening on (default 9003) is not blocked.
A: If you are running with SELinux you should make sure it is not preventing connections; look for warnings about name_connect or anything related to the Xdebug port. You might have to allow access explicitly. Visit this site or search for "selinux name_connect apache" for more information about how to do this

Compilation and Configuration

Q: I don't have the phpize tool.
A: Debian and Ubuntu users need to install the PHP development package with apt install php-dev. openSUSE Leap users can install it with zypper install php7-devel.
Q: What to do with: Xdebug requires Zend Engine API version xxxxxxxx. The Zend Engine API version 2xxxxxxxx which is installed, is newer.
A: This message means that you are trying to load Xdebug with a PHP version for which it wasn't built. If you compiled PHP yourself, it is most likely because you compiled Xdebug against PHP headers that belong to a different PHP version that you're running. For example, you're using PHP 5.3 and the headers you're using are still PHP 5.2. If you are using a pre-compiled binary, then you're using the wrong one.
To diagnose if this is your problem, make the following steps:
  • Check what the "Zend Extension" API number is of the PHP version that you are running by looking at phpinfo() (or "php -i") output. You can find it in the top part of the output, in the same block as the PHP logo and the PHP version. As examples, for PHP 5.2, the number is "220060519" and for PHP 5.3 it is "220090626".
  • Check what the output of "phpize" is when you're completing the compilation steps. The number that you're looking for is on the line that says "Zend Extension Api No".

If the two numbers from above do not match, you're compiling with the wrong PHP headers. Refer to the next FAQ entry to figure out which phpize to use.

Q: Xdebug is only loaded as PHP extension and not as a Zend Extension.

The tailored installation instructions might have you pointed to this entry.

In order for Xdebug to work properly, including breakpoints etc. it is required that it is loaded as a Zend extension, and not just as a normal PHP extension. Some installation tools (PEAR/PECL) sometimes advice you to use extension=xdebug.so to load Xdebug. This is not correct. In order to fix this issue, please look for a line extension=xdebug.so in any of the INI files that are listed under "Loaded Configuration File" and "Additional .ini files parsed" in the top block. Remove this line, and go back to the Tailored Installation Instructions.

Q: How do I find which phpize to use?
A: Run: "phpize --help". This shows you the full path to phpize. This path should be the same as where you have the CLI binary, "php-config" and the "pear" and "pecl" binaries installed. If you run "php-config --version" it should show the same version of PHP that you're running. If it doesn't match up, and perhaps the wrong "phpize" binary is found on the path, you can run configure as follows:
  1. /full/path/to/php/bin/phpize
  2. ./configure --with-php-config=/full/path/to/php/bin/php-config
Q: I'm using XAMPP, but I can't seem to get the packaged xdebug extension to work properly.
A: If you uncommented the "extension=php_xdebug.dll" line, that is to be expected. Xdebug needs to be loaded with the zend_extension_ts= "C:\path\to\php_xdebug.dll" directive. You'll also likely have to disable the loading of the Zend Optimizer, since it's enabled by default, and doesn't work well with Xdebug. So look for the related entry in php.ini, and comment it out. From PHP 5.3 onwards, you always need to use the zend_extension PHP.ini setting name, and not zend_extension_ts.
Q: On Debian, I am seeing the following problem with the build of Xdebug.... any fixes? 
/usr/lib/libc_nonshared.a(stat.oS)(.text.__i686.get_pc_thunk.bx+0x0):
In function `__i686.get_pc_thunk.bx':
: multiple definition of `__i686.get_pc_thunk.bx'
/usr/lib/gcc-lib/i486-linux/3.3.5/crtbeginS.o
(.gnu.linkonce.t.__i686.get_pc_thunk.bx+0x0): first defined here
collect2: ld returned 1 exit status
make: *** [xdebug.la] Error 1
A: This is an issue with Debian itself, see for more information here and here.

Precompiled Binaries

I get a "not found" or similar error message when I start a precompiled Linux binary such as dbgpClient or dbgpProxy.

The provided binaries are compiled by Go, which generates static binaries. The only requirement is that libc6 is available on the system. Some distributions use a different C library by default. Alpine Linux for example uses musl. In order to make the binaries run, you will therefore need to install a libc6 compatibility package.

For Alpine Linux, you can install this with: apk add libc6-compat.