Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

PHP mkdir() fails with Permission denied inside a container

ErrorWarning: mkdir(): Permission denied in /var/www/html/upload.php

Short answer

mkdir() fails when the user running PHP cannot write to the parent folder. In Docker this is often a folder copied in as root while PHP runs as another user. Check the parent folder's owner against the PHP user first, then open_basedir, then the permissions mkdir gave the new folder.

  • Applies to PHP 8.3, PHP 8.4, Docker Engine 27
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Compare the user PHP runs as with the owner and mode of the parent folder, from inside the container.

    docker exec -it my-app sh -c 'id; ls -ld /var/www/html/uploads'
  2. 2Match what you see, then jump to its fix

    1. 1ls -ld shows owner root and mode drwxr-xr-x, while id shows a different user such as www-data.The parent folder belongs to root and PHP runs as another userFix
    2. 2The warning mentions open_basedir restriction in effect, or the path is outside the folders your configuration allows.open_basedir blocks the pathFix
    3. 3mkdir() succeeds, but another user or process later gets Permission denied inside the new folder.The new folder got narrower permissions than you expectedFix

What does the error look like?

  • Warning: mkdir(): Permission denied in /var/www/html/upload.php
  • mkdir(): Permission denied

Cause 1 of 3

The parent folder belongs to root and PHP runs as another user

1Check

The mkdir manual lists restricted permissions as a cause of the warning. In a Dockerfile, COPY gives files UID and GID 0 unless you use --chown, and USER sets who the process runs as.

docker exec -it my-app sh -c 'id; ls -ld /var/www/html /var/www/html/uploads'

2Fix

Give the folder to the runtime user at build time with COPY --chown, or create it in the image with the right owner.

COPY --chown=www-data:www-data . /var/www/html
USER www-data

3Verify

Rebuild, start the container and call mkdir() again.

docker compose up -d --build
docker exec -it my-app php -r "var_dump(mkdir('/var/www/html/uploads/test'));"

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 3

open_basedir blocks the path

1Check

open_basedir limits file access to the listed directory tree, and a path outside it is refused. Matching is by directory, not by prefix: /www/tmp does not allow /www/tmpfiles.

php -r "var_dump(ini_get('open_basedir'));"

2Fix

Add the target directory to open_basedir (separate paths with a colon on Linux), or write inside a folder that is already allowed.

; php.ini
open_basedir = "/var/www/html:/tmp"

3Verify

Reload PHP and repeat the mkdir() call.

php -r "var_dump(mkdir('/var/www/html/uploads/test2'));"

Confirmed by php.net

Did this fix it?

Cause 3 of 3

The new folder got narrower permissions than you expected

1Check

The manual says the requested mode is modified by the current umask, and that the mode is ignored on Windows. The folder can therefore end up with fewer permission bits than the mode you passed.

docker exec -it my-app php -r "echo decoct(umask()), PHP_EOL;"
docker exec -it my-app ls -ld /var/www/html/uploads/test

2Fix

Create the folder with the mode you need and set the umask only around that call, or use chmod() afterwards.

<?php
$old = umask(0);
mkdir('/var/www/html/uploads/shared', 0775, true);
umask($old);

3Verify

List the folder again and compare the mode.

docker exec -it my-app ls -ld /var/www/html/uploads/shared

Confirmed by php.net

Did this fix it?

How do I stop it coming back?

  • Decide the runtime user once (USER in the Dockerfile) and use COPY --chown for every folder it writes to.
  • Keep writable folders in one place, such as a dedicated uploads path.
  • Pass true as the third argument of mkdir() when parent folders may be missing, and check the return value.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

composer require laravel/horizon fails: ext-pcntl is missing

laravel/horizon v1.1.0 requires ext-pcntl * -> the requested PHP extension pcntl is missing from your system

Horizon needs the pcntl extension, and Composer refuses to install it where PHP lacks that extension.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.