What causes "Error creating thumbnail directory" in octobercms/october?

chown -R www-data:www-data storage (or chmod -R u+rwX) so the PHP user can create directories under the temp path.

octobercms/october · error · SystemException

Error creating thumbnail directory

Error message

Error creating thumbnail directory

What it means

SystemException thrown in resizeImage() (MediaManager.php:1449) when the thumbnail's parent directory does not exist and File::makeDirectory(..., 0755, true) fails to create it. Thumbnails are cached under temp_path() in a nested path derived from the thumbnail parameters, so this is an environment-level failure, not bad user input.

Source

Thrown at modules/media/widgets/MediaManager.php:1449

            ];
        }
    }

    /**
     * resizeImage
     * @param string $fullThumbnailPath
     * @param array $thumbnailParams
     * @param string $tempFilePath
     * @return void
     */
    protected function resizeImage($fullThumbnailPath, $thumbnailParams, $tempFilePath)
    {
        $thumbnailDir = dirname($fullThumbnailPath);
        if (
            !File::isDirectory($thumbnailDir)
            && File::makeDirectory($thumbnailDir, 0755, true) === false
        ) {
            throw new SystemException('Error creating thumbnail directory');
        }

        $targetDimensions = $this->getTargetDimensions($thumbnailParams['width'], $thumbnailParams['height'], $tempFilePath);

        $targetWidth = $targetDimensions[0];
        $targetHeight = $targetDimensions[1];

        Resizer::open($tempFilePath)
            ->resize($targetWidth, $targetHeight, [
                'mode' => $thumbnailParams['mode'],
                'offset' => [0, 0]
            ])
            ->save($fullThumbnailPath)
        ;

        File::chmod($fullThumbnailPath);
    }

View on GitHub (pinned to b608633a7e)

Solutions

chown -R www-data:www-data storage (or chmod -R u+rwX) so the PHP user can create directories under the temp path.
Point temp to a writable volume: set cms.tempDir / use a mounted path for temp_path() in containerised setups.
Verify with sudo -u www-data mkdir <thumbnailDir> that creation succeeds; check SELinux audit logs if applicable.

Defensive patterns

Strategy: validation

Validate before calling

// Boot-time guard: ensure the thumbnails temp root is writable
$dir = temp_path('public');
if (!is_dir($dir)) {
    @mkdir($dir, 0755, true);
}
if (!is_writable($dir)) {
    throw new RuntimeException('Temp path not writable: ' . $dir);
}

Try / catch

try {
    $this->resizeImage($fullPath, $params, $tempFile);
} catch (\System\Classes\SystemException $e) {
    \Log::error('Cannot create thumbnail dir: ' . $e->getMessage());
    return $this->makePartial('thumbnail-image', ['isError' => true]);
}

Prevention

chown storage/ to the PHP-FPM user in every deployment script.
Mount a writable volume at the temp path in containers.
Include a temp-path writability check in your health endpoint.

When it happens

Trigger: Generating a thumbnail whose target directory (temp path + hashed thumbnail path) cannot be created: directory owned by root after a deployment, read-only filesystem or container image, SELinux denying mkdir, or a full disk returning errors.

Common situations: Deployments where storage/ was copied with wrong ownership; Docker/Kubernetes containers with a read-only layer where temp_path() resolves inside the app; SELinux contexts on CentOS/RHEL; running under a different PHP-FPM user than the one that owns storage/.

Related errors

AI-assisted analysis of octobercms/october@b608633a7e (2026-08-21). Data as JSON: /api/errors/2ecbcdc7151e7f56. Report an issue: GitHub.