phalcon/cphalcon · error · Phalcon\Mvc\Router\Exception

Failed to write router cache temp file: {tmpPath}

Error message

Failed to write router cache temp file: {tmpPath}

What it means

dumpDispatcher() writes the serialized router dump to a temp file next to the target (path . '.tmp.' . getmypid()) before atomically renaming it into place. If the low-level write fails (file_put_contents returns false), it throws with the concrete temp path. This is a filesystem-level failure: unwritable directory, missing directory, full disk, or path restrictions.

Source

Thrown at phalcon/Mvc/Router.zep:932

    }

    /**
     * File-shaped helper around buildDispatcherDump(). Writes the dump as
     * a `<?php return [...];` file, atomically (temp + rename) so concurrent
     * dumps don't corrupt the result.
     *
     * @throws \Phalcon\Mvc\Router\Exception
     */
    public function dumpDispatcher( string path) -> void
    {
        var dump, php, tmpPath;

        let dump    = this->buildDispatcherDump();
        let php     = "<?php\nreturn " . var_export(dump, true) . ";\n";
        let tmpPath = path . ".tmp." . (string) getmypid();

        if this->phpFilePutContents(tmpPath, php) === false {
            throw new Exception("Failed to write router cache temp file: " . tmpPath);
        }

        if !rename(tmpPath, path) {
            this->phpUnlink(tmpPath);
            throw new Exception("Failed to commit router cache: " . path);
        }
    }

    /**
     * File-shaped helper around loadDispatcherFromArray(). Includes the
     * file (opcache-friendly) and forwards the return value.
     *
     * @throws \Phalcon\Mvc\Router\Exception
     */
    public function loadDispatcher( string path) -> void
    {
        var dump;

View on GitHub (pinned to b7419de9cd)

Solutions

  1. Ensure the cache directory exists and is writable by the exact PHP/runtime user: mkdir -p + chown/chmod (e.g. chmod 775 with correct group)
  2. Move the cache path to a directory designed for writes (var/cache of the app, /tmp-based dir), or mount it writable in containers
  3. Check free disk space and quota on the cache volume
  4. If open_basedir is active, verify the cache directory is inside an allowed path
  5. Wrap the dump call in try/catch (Phalcon\Mvc\Router\Exception) and log the tmpPath from the message for diagnosis

Example fix

// before
$router->dumpDispatcher('/var/www/app/cache/routes.php'); // dir not writable -> throws

// after: ensure the dir exists and is writable for the runtime user
$dir = '/var/www/app/cache';
if (!is_dir($dir)) { mkdir($dir, 0775, true); }
if (!is_writable($dir)) { throw new RuntimeException("Cache dir not writable: {$dir}"); }
$router->dumpDispatcher($dir . '/routes.php');

# shell equivalent
# mkdir -p /var/www/app/cache && chown www-data:www-data /var/www/app/cache
Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-flight the cache target before dumping
$dir = dirname($path);
if (!is_dir($dir) || !is_writable($dir)) {
    throw new RuntimeException("Router cache directory missing or not writable: {$dir}");
}
if (disk_free_space($dir) < 1048576) {
    throw new RuntimeException('Insufficient disk space for router cache');
}
$router->dumpDispatcher($path);

Try / catch

try {
    $router->dumpDispatcher($path);
} catch (\Phalcon\Mvc\Router\Exception $e) {
    // message contains the tmp path - log it and continue without cache
    $logger->warning($e->getMessage());
    $routesBuiltDynamically = true; // fall back to runtime-built routes
}

Prevention

When it happens

Trigger: Calling dumpDispatcher('/var/cache/app/routes.php') when /var/cache/app is not writable by the PHP user; passing a path whose parent directory does not exist; disk full on the cache volume; open_basedir restriction excluding the cache directory; read-only filesystem in a container.

Common situations: Deploy-time cache generation where the CI user owns the file but the web/PHP user cannot write (or vice versa); Docker images with read-only layers where the cache path was not mounted writable; shared hosting with restrictive open_basedir; disk exhaustion during cache rebuilds.

Related errors

AI-assisted analysis of phalcon/cphalcon@b7419de9cd (2026-08-21). Data as JSON: /api/errors/ad8148038b7281da. Report an issue: GitHub.