What causes "Failed to cache configuration" in OpenAPITools/openapi-generator?

Create and grant write access: mkdir -p data/cache && chown -R www-data:www-data data (or chmod -R 775 data/cache) so the web/CLI user can write.

OpenAPITools/openapi-generator · error · RuntimeException

Failed to cache configuration

Error message

Failed to cache configuration

What it means

In the generated php-mezzio-ph skeleton, container.php merges the YAML config files and, when 'cache_configuration: true' is set in config.yml, writes the merged config to data/cache/config.php via ConfigFactory::toFile (CONFIG_CACHE_PATH, line 13). If that write returns false — almost always because the data/cache directory is missing or not writable by the PHP process user — a RuntimeException 'Failed to cache configuration' aborts container bootstrapping on every request.

Source

Thrown at modules/openapi-generator/src/main/resources/php-mezzio-ph/container.php:34

$config = [];
if (is_readable(CONFIG_CACHE_PATH)) {
    $config = include CONFIG_CACHE_PATH;
} else {
    //Register extra extension for YAML files
    ConfigFactory::registerReader('yml', 'yaml');

    //Combine all configuration files in right order
    $config = ConfigFactory::fromFiles([
        __DIR__ . '/config/data_transfer.yml',
        __DIR__ . '/config/path_handler.yml',
        __DIR__ . '/config/app.yml',
        __DIR__ . '/config.yml',
    ]);

    //Cache full configuration
    if ($config['cache_configuration'] ?? false) {
        if (!ConfigFactory::toFile(CONFIG_CACHE_PATH, $config)) {
            throw new \RuntimeException('Failed to cache configuration');
        }
    }
}

//Create container
$container = new \Laminas\ServiceManager\ServiceManager($config['dependencies'] ?? []);

//Register full configuration as a service
$container->setService('config', $config);
$container->setAlias('Config', 'config');

return $container;

View on GitHub (pinned to fcec517be3)

Solutions

Create and grant write access: mkdir -p data/cache && chown -R www-data:www-data data (or chmod -R 775 data/cache) so the web/CLI user can write.
For development, set cache_configuration: false in config/config.yml to skip caching entirely.
Remove a stale, unreadable data/cache/config.php (rm data/cache/config.php) after permission changes, since a cached file is preferred once readable.

Example fix

# before
# config.yml: cache_configuration: true, but data/cache missing
php public/index.php
# RuntimeException: Failed to cache configuration

# after
mkdir -p data/cache
chown -R www-data:www-data data
cache_configuration: true  # works now
# or in config.yml for dev:
cache_configuration: false

Defensive patterns

Strategy: validation

Validate before calling

<?php
// run before the container boots, e.g. in public/index.php during deploys
$cacheDir = dirname(CONFIG_CACHE_PATH);
if (($config['cache_configuration'] ?? false)
    && (!is_dir($cacheDir) || !is_writable($cacheDir))) {
    throw new RuntimeException(
        "data/cache is missing or not writable; run: mkdir -p $cacheDir && chown -R <php-user> " . dirname($cacheDir)
    );
}

Try / catch

try {
    $container = require __DIR__ . '/container.php';
} catch (\RuntimeException $e) {
    if (strpos($e->getMessage(), 'Failed to cache configuration') !== false) {
        // permissions problem: surface an actionable message instead of a 500
        error_log('config cache unwritable: fix data/cache permissions or set cache_configuration: false');
    }
    throw $e;
}

Prevention

Make the deploy pipeline create data/cache with the PHP-FPM user as owner.
Keep cache_configuration: false outside production; enable it only where the dir is provably writable.
Never run composer/console as root in the app dir — it leaves root-owned cache files.

When it happens

Trigger: Freshly generated Mezzio app with cache_configuration: true where data/cache does not exist (not committed to git) or is owned by root/another user; deploying behind PHP-FPM where the www-data user cannot write the directory; read-only container filesystems.

Common situations: Cloning a generated project on a new machine or CI runner and hitting the cache write immediately; Docker images running as a non-root user without chown of the app dir; cache file left root-owned after running composer/console as root once.

Related errors

AI-assisted analysis of OpenAPITools/openapi-generator@fcec517be3 (2026-08-22). Data as JSON: /api/errors/f53f131152bad0ec. Report an issue: GitHub.