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

Router cache not found: {path}

Error message

Router cache not found: {path}

What it means

loadDispatcher(path) requires an existing router cache file (produced earlier by dumpDispatcher()). If the file is missing at the given path it throws immediately - loading is deliberately strict so stale/absent caches fail loudly instead of silently degrading route matching. The companion dump call is how the file is supposed to come into existence.

Source

Thrown at phalcon/Mvc/Router.zep:952

        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;

        if !this->phpFileExists(path) {
            throw new Exception("Router cache not found: " . path);
        }

        let dump = require path;

        if typeof dump !== "array" {
            throw new Exception(
                "Router cache is corrupt or invalid (expected array, got " . gettype(dump) . "): " . path
            );
        }

        this->loadDispatcherFromArray(dump);
    }

    /**
     * Cache-instance convenience wrapper. On cache hit, restores the
     * dispatcher immediately. On miss, defers cache population until the
     * next handle() completes - at which point buildDispatcherDump() is
     * written to the cache key.

View on GitHub (pinned to b7419de9cd)

Solutions

1. Generate the cache before loading: call buildRoutes($router)->dumpDispatcher($path) during deploy/build, then loadDispatcher($path) at runtime
2. Guard with file_exists($path) and fall back to building routes dynamically on miss
3. Use absolute paths computed from a single root so CLI and web resolve the same file
4. Ensure the cache file is present on every node/image that will load it

Example fix

// before
$router->loadDispatcher($cachePath); // file never generated -> throws

// after: build-on-miss pattern
if (!file_exists($cachePath)) {
    buildRoutes($router)->dumpDispatcher($cachePath);
}
$router->loadDispatcher($cachePath);

if (!is_file($cachePath)) {
    buildRoutes($router)->dumpDispatcher($cachePath); // build on first run
}
$router->loadDispatcher($cachePath);

try {
    $router->loadDispatcher($cachePath);
} catch (\Phalcon\Mvc\Router\Exception $e) {
    buildRoutes($router); // fall back to dynamic routes this request
    // optionally schedule a rebuild
}

When it happens

Trigger: Calling loadDispatcher('/cache/routes.php') before dumpDispatcher() has ever run on this host; typo'd path; the cache file is not shipped in the container image or was cleaned by a cache-clear task; deploying code that loads the cache but forgetting the build step that generates it.

Common situations: Separating 'dump at build time' from 'load at runtime' but the build step never ran; container images that exclude var/cache; multi-server setups where only one node generated the cache; relative paths resolving differently between CLI (dump) and web (load) contexts.

Related errors

• Cannot cache router: route id '{routeId}' has a Closure befo
• Cannot cache router: route id '{routeId}' has a Closure conv
• Router cache is missing 'version' field
• Router cache version {dumpVersion} is not supported (this bu
• Router cache is missing 'routes' field

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