{"record":{"id":"6fc9e9c4788bcf16","repo":"phalcon/cphalcon","slug":"router-cache-version-dumpversion-is-not-supporte","errorCode":null,"errorMessage":"Router cache version {dumpVersion} is not supported (this build supports version 1)","messagePattern":"Router cache version (.+?) is not supported \\(this build supports version 1\\)","errorType":"exception","errorClass":"Phalcon\\Mvc\\Router\\Exception","httpStatus":null,"severity":"error","filePath":"phalcon/Mvc/Router.zep","lineNumber":829,"sourceCode":"     *\n     * @throws \\Phalcon\\Mvc\\Router\\Exception\n     */\n    public function loadDispatcherFromArray(array dump) -> void\n    {\n        var routeData, route, routeClass, beforeMatch, converters,\n            convName, converter, rebuiltRoutes, methodRoutesRehydrated,\n            candidatesRehydrated, staticRehydrated, innerKey, innerVal,\n            scalarIdx, scalarSubKey, mostInnerVal, mostInnerArr;\n        int dumpVersion;\n\n        if !isset dump[\"version\"] {\n            throw new Exception(\"Router cache is missing 'version' field\");\n        }\n\n        let dumpVersion = (int) dump[\"version\"];\n\n        if dumpVersion !== 1 {\n            throw new Exception(\n                \"Router cache version \" . dumpVersion . \" is not supported (this build supports version 1)\"\n            );\n        }\n\n        if !isset dump[\"routes\"] {\n            throw new Exception(\"Router cache is missing 'routes' field\");\n        }\n\n        let rebuiltRoutes = [];\n\n        for routeData in dump[\"routes\"] {\n            let routeClass = routeData[\"class\"];\n            let route      = new {routeClass}(routeData[\"pattern\"], routeData[\"paths\"], routeData[\"methods\"]);\n\n            if routeData[\"hostname\"] !== null {\n                route->setHostname(routeData[\"hostname\"]);\n            }\n","sourceCodeStart":811,"sourceCodeEnd":847,"githubUrl":"https://github.com/phalcon/cphalcon/blob/b7419de9cd0a8a3f48441ead84c9f8415d463e25/phalcon/Mvc/Router.zep#L811-L847","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Delete the stale cache (file or cache key) and let it be regenerated by the current build: dumpDispatcher() / useCache() miss path","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","In deployment, add a step that clears router caches after a framework upgrade","Catch Phalcon\\Mvc\\Router\\Exception on load and fall back to rebuilding routes dynamically"],"exampleFix":"// before\n$router->loadDispatcher($cachePath); // cache written by older Phalcon -> throws\n\n// after: version-scoped cache path per build\n$version = str_replace('.', '', phpversion('phalcon')); // or Phalcon version constant\n$path = $cacheDir . '/router.dispatcher.v' . $version . '.php';\nif (!is_file($path)) {\n    buildRoutes($router)->dumpDispatcher($path);\n}\n$router->loadDispatcher($path);","handlingStrategy":"validation","validationCode":"$dump = require $path;\nif (($dump['version'] ?? null) !== 1) {\n    unset($dump);            // stale format from another build\n    unlink($path);           // discard\n    buildRoutes($router)->dumpDispatcher($path);\n    $dump = require $path;\n}\n$router->loadDispatcherFromArray($dump);","typeGuard":"function isSupportedDumpVersion(mixed $dump): bool\n{\n    return is_array($dump) && (int)($dump['version'] ?? 0) === 1;\n}","tryCatchPattern":"try {\n    $router->loadDispatcher($path);\n} catch (\\Phalcon\\Mvc\\Router\\Exception $e) {\n    // version mismatch: drop the cache and rebuild with this build\n    @unlink($path);\n    buildRoutes($router)->dumpDispatcher($path);\n    $router->loadDispatcher($path);\n}","preventionTips":["Scope the cache path/key by Phalcon version so upgrades cannot read old dumps","Clear router caches as an explicit step in every framework upgrade runbook","In multi-version deployments (canaries), never share one cache slot between builds"],"tags":["phalcon","router","caching","version-mismatch","upgrade"],"backgroundTag":"cache-schema-mismatch","analyzedSha":"b7419de9cd0a8a3f48441ead84c9f8415d463e25","analyzedAt":"2026-08-21T06:21:18.811Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}