octobercms/october · error · Exception

The {$this->manifestPath} directory must be present and writ

Error message

The {$this->manifestPath} directory must be present and writable.

What it means

ManifestCache persists the CMS manifest (registered plugins, modules, etc.) as a PHP array file at cache_path('cms/manifest.php') and writes it on shutdown after registrations. write() throws a plain Exception when dirname(manifestPath) — the framework cache directory, by default storage/framework/cache — is missing or not writable. Note useManifest is disabled in debug mode (useManifest = !System::checkDebugMode()), so this frequently surfaces only in production.

Source

Thrown at modules/system/classes/ManifestCache.php:154

            }
        }

        $this->manifest += $manifest;

        $this->manifestLoaded = true;
    }

    /**
     * write the given manifest array to disk
     */
    protected function write(array $manifest)
    {
        if (!$this->useManifest || $this->manifestPath === null) {
            return;
        }

        if (!is_writable(dirname($this->manifestPath))) {
            throw new Exception("The {$this->manifestPath} directory must be present and writable.");
        }

        File::put(
            $this->manifestPath,
            '<?php return '.var_export($manifest, true).';'
        );
    }
}

View on GitHub (pinned to b608633a7e)

Solutions

1. Create the directory: mkdir -p storage/framework/cache.
2. Give the web/CLI user write access: chown -R www-data:www-data storage (or chmod -R ug+rwx storage as appropriate).
3. Run artisan and web requests as the same user to avoid root-owned cache files.
4. If cache_path was customized, verify the configured directory exists and is writable.

Example fix

# before
$ php artisan cache:clear
Exception: The /app/storage/framework/cache/cms/manifest.php directory must be present and writable.

# after
$ mkdir -p storage/framework/cache
$ chown -R www-data:www-data storage
$ php artisan cache:clear

// Pre-flight in a deploy script or service provider boot
$manifestDir = dirname(cache_path('cms/manifest.php'));
if (!is_dir($manifestDir)) {
    mkdir($manifestDir, 0775, true);
}
if (!is_writable($manifestDir)) {
    throw new RuntimeException("Cache directory {$manifestDir} is not writable by " . get_current_user());
}

When it happens

Trigger: Deploying to a fresh server where storage/framework/cache was never created; running php artisan optimize / cache:clear or any request that mutates the manifest as a user without write permission (root-owned files from a root deploy); moved/custom cache path that does not exist; open_basedir or SELinux blocking the directory.

Common situations: Post-deploy permission drift after uploading as root and serving as www-data; CI pipelines that run composer/artisan as a different user than the web server; containerized setups where the storage volume mount is read-only; local environments copied without the storage skeleton.

Understand the failure class

Background: Permission denied / not authorized / 403 Forbidden: access-control rejections when the caller lacks the required role, grant, or ownership — this error's family across 18 libraries.

Related errors

• cms::lang.cms_object.error_creating_directory
• editor::lang.filesystem.error_creating_directory
• The combiner file ':name' is not found.
• cms::lang.cms_object.error_saving
• cms::lang.lang.error_deleting_file

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