Skip to content

Troubleshooting PHP FPM and FastCGI

Duncan Ogilvie edited this page Jul 27, 2017 · 8 revisions

Caddy supports PHP via FastCGI directive. Many of our users are up and running with PHP with no hassle but there are some that run into issues.

This wiki focuses more on Caddy and installing/configuring PHP-FPM is assumed to be known by the user.

These are some valuable troubleshooting tips.

Enable Error Logging

This is first step to troubleshooting. You can enable it with a simple single line syntax.

errors errors.log


Any change to the Caddyfile requires Caddy restart

Any change to PHP-FPM config (usually php-fpm.conf or www.conf) requires PHP-FPM restart.

Malformed MIME Header

Sample error:

[ERROR 502 /index.php] malformed MIME header line: Primary script unknown

Update to Caddy 0.8.1. This will either fix it or get you a more descriptive error message. On Unix-like systems this issue can also occur because Caddy and php-fpm aren't running under the same user/group. Make sure you run them under the same user/group and give proper permissions to the document root folder (chmod/chown). Also check your chroot setting in the php-fpm configs (pool.d/www.conf).

Connection refused

Sample error:

[ERROR 502 /index.php] dial tcp getsockopt: connection refused

Ensure PHP-FPM is running and listening on the specified port. Double check php-fpm.conf if required.

listen = 9000

No such file or directory

Sample error:

[ERROR 502 /index.php] dial unix /var/run/php5-fpm.sock: connect: no such file or directory

Ensure PHP-FPM is running and listening on the specified unix socket. Double check php-fpm.conf if required.

listen = /var/run/php5-fpm.sock

Ensure the user running Caddy has read permission to the unix socket file.

Permission denied

Sample error:

[ERROR 502 /info.php] dial unix /var/run/php5-fpm.sock: connect: permission denied

This error occurs if you are not running caddy as the www-data user. To fix it change /etc/php5/fpm/pool.d/www.conf or /etc/php/7.0/fpm/pool.d/www.conf, depending on your version and change the user:

listen.owner = caddy = caddy


PHP frameworks generally needs rewrite; either as a requirement or for clean urls. Update to Caddy 0.8.1, the version that introduced more powerful rewrites, then read the docs.

The format below would satisfy some of the popular frameworks.

rewrite {
    to {path} {path}/ /index.php?url={uri}

Some frameworks require escaped version of the value to fit in as valid query parameter.

rewrite {
    to {path} {path}/ /index.php?url={path_escaped}&{query}

Or if the project is inside a subdirectory, use regex to capture the subpath.

rewrite /subdirectory/ {
    r (.*)
    to {path} {path}/ /subdirectory/index.php?url={1}&{query}


How are you using PHP with Caddy? We would appreciate your contributions to our examples repository

You can’t perform that action at this time.