Troubleshooting PHP FPM and FastCGI

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

Restart

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).

Connection refused

Sample error:

[ERROR 502 /index.php] dial tcp 127.0.0.1:9000: 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.

Rewrite

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

Examples

How are you using PHP with Caddy? We would appreciate your contributions to our examples repository github.com/caddyserver/examples.