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

Router cache version {dumpVersion} is not supported (this bu

Error message

Router cache version {dumpVersion} is not supported (this build supports version 1)

What it means

The router dispatcher cache format carries a version stamp ('version' => 1 at the time of this code). loadDispatcherFromArray() refuses dumps whose version differs from what this build of Phalcon supports, because the internal shape (route metadata, method index, candidate maps) may have changed between releases. The reported number is the dump's version, not the library's.

Source

Thrown at phalcon/Mvc/Router.zep:829

     *
     * @throws \Phalcon\Mvc\Router\Exception
     */
    public function loadDispatcherFromArray(array dump) -> void
    {
        var routeData, route, routeClass, beforeMatch, converters,
            convName, converter, rebuiltRoutes, methodRoutesRehydrated,
            candidatesRehydrated, staticRehydrated, innerKey, innerVal,
            scalarIdx, scalarSubKey, mostInnerVal, mostInnerArr;
        int dumpVersion;

        if !isset dump["version"] {
            throw new Exception("Router cache is missing 'version' field");
        }

        let dumpVersion = (int) dump["version"];

        if dumpVersion !== 1 {
            throw new Exception(
                "Router cache version " . dumpVersion . " is not supported (this build supports version 1)"
            );
        }

        if !isset dump["routes"] {
            throw new Exception("Router cache is missing 'routes' field");
        }

        let rebuiltRoutes = [];

        for routeData in dump["routes"] {
            let routeClass = routeData["class"];
            let route      = new {routeClass}(routeData["pattern"], routeData["paths"], routeData["methods"]);

            if routeData["hostname"] !== null {
                route->setHostname(routeData["hostname"]);
            }

View on GitHub (pinned to b7419de9cd)

Solutions

1. Delete the stale cache (file or cache key) and let it be regenerated by the current build: dumpDispatcher() / useCache() miss path
2. Include the Phalcon version in the cache key or file path (e.g. 'router.dispatcher.v' . phpversion('phalcon') or PackageInfo version) so each build uses its own slot
3. In deployment, add a step that clears router caches after a framework upgrade
4. Catch Phalcon\Mvc\Router\Exception on load and fall back to rebuilding routes dynamically

Example fix

// before
$router->loadDispatcher($cachePath); // cache written by older Phalcon -> throws

// after: version-scoped cache path per build
$version = str_replace('.', '', phpversion('phalcon')); // or Phalcon version constant
$path = $cacheDir . '/router.dispatcher.v' . $version . '.php';
if (!is_file($path)) {
    buildRoutes($router)->dumpDispatcher($path);
}
$router->loadDispatcher($path);

$dump = require $path;
if (($dump['version'] ?? null) !== 1) {
    unset($dump);            // stale format from another build
    unlink($path);           // discard
    buildRoutes($router)->dumpDispatcher($path);
    $dump = require $path;
}
$router->loadDispatcherFromArray($dump);

function isSupportedDumpVersion(mixed $dump): bool
{
    return is_array($dump) && (int)($dump['version'] ?? 0) === 1;
}

try {
    $router->loadDispatcher($path);
} catch (\Phalcon\Mvc\Router\Exception $e) {
    // version mismatch: drop the cache and rebuild with this build
    @unlink($path);
    buildRoutes($router)->dumpDispatcher($path);
    $router->loadDispatcher($path);
}

When it happens

Trigger: Loading a dispatcher cache produced by a different Phalcon release (upgraded the extension but kept old cache files); multiple app versions sharing one cache file path or key; rolling back a deploy while keeping the newer version's cache.

Common situations: Phalcon upgrade followed by reusing a pre-existing cache directory; blue/green or canary deploys where two builds share a cache store; cache files baked into a container image built from a different Phalcon version than the runtime.

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 is missing 'routes' field
• Failed to write router cache temp file: {tmpPath}

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