Troubleshooting

Common issues

Find your symptom below. Each entry gives the cause and the fix. If yours isn't here, see getting help.

The page doesn't load on port 80 or 443

Cause: The containers run unprivileged, so the web server listens on 8080 for HTTP and 8443 for HTTPS, not 80 and 443. The fpm image listens on 9000 for FastCGI and serves no HTTP.

Fix: Map your host ports to the container's ports:

compose.yml
services:
  php:
    image: serversideup/php:8.5-fpm-nginx
    ports:
      - 80:8080
      - 443:8443

Port is already allocated or in use

Docker reports one of these when the container starts:

Bind for 0.0.0.0:80 failed: port is already allocated
listen tcp4 0.0.0.0:80: bind: address already in use

Cause: Another container or program on your host is using that port.

Fix: Stop the other program, or map a different host port, such as 8000:8080, and open http://localhost:8000. To find what is using the port, run sudo lsof -i :80 on Linux or macOS, or netstat -ano | findstr :80 on Windows.

404 or "File not found" for every page

Cause: The web server's document root is /var/www/html/public. An app with index.php in its project root, instead of in public/, has nothing to serve.

Fix: Move your public files into public/, or point the document root at your folder. The variable depends on the image:

ImageVariable
fpm-nginxNGINX_WEBROOT
fpm-apacheAPACHE_DOCUMENT_ROOT
frankenphpCADDY_SERVER_ROOT

For example, NGINX_WEBROOT: "/var/www/html".

Code changes don't show up

Cause: OPcache is on (PHP_OPCACHE_ENABLE=1) and, by default, never checks files for changes (PHP_OPCACHE_VALIDATE_TIMESTAMPS=0). PHP keeps serving the compiled copy until the container restarts. Unless SHOW_WELCOME_MESSAGE=false, the startup log says so: OPcache is enabled and PHP_OPCACHE_VALIDATE_TIMESTAMPS=0. Code changes require a container restart.

Fix: In development, leave PHP_OPCACHE_ENABLE at its default of 0, or set PHP_OPCACHE_VALIDATE_TIMESTAMPS=1. In production, deploy a new container. See production performance tuning.

Permission denied when writing files

Cause: With your code mounted from the host, the container's www-data user (UID 33 on Debian, 82 on Alpine) doesn't own your files, so PHP can't write to directories like storage/. Files it does create belong to UID 33 on your host.

Fix: Build a development image that gives www-data your UID and GID. See understanding file permissions.

Permission denied during docker build

Cause: The images run as www-data, so RUN steps that install packages or extensions can't write to system directories.

Fix: Switch to root for those steps and back afterward:

Dockerfile
FROM serversideup/php:8.5-fpm-nginx

USER root
RUN install-php-extensions intl
USER www-data

The container stops right after it starts

Cause: A script in /etc/entrypoint.d/ exited with an error, which stops the container before PHP or the web server starts. This includes your own scripts and Laravel automations, for example when migrations can't reach the database.

Fix: Read the last lines of docker compose logs. Set LOG_OUTPUT_LEVEL=debug to log each script's name as it runs, so you can see which one failed. See adding start up scripts.

502 Bad Gateway with "upstream sent too big header"

Cause: In fpm-nginx, a PHP response's headers (often large cookies) are bigger than NGINX's FastCGI buffer, which is 8k by default. The NGINX log shows upstream sent too big header while reading response header from upstream.

Fix: Raise the buffer sizes:

compose.yml
services:
  php:
    image: serversideup/php:8.5-fpm-nginx
    environment:
      NGINX_FASTCGI_BUFFER_SIZE: "32k"
      NGINX_FASTCGI_BUFFERS: "16 16k"

Before you ask for help

Collect the image tag, your compose.yml or Dockerfile, and the full log output from docker compose logs. Then see getting help.