{"record":{"id":"471b363e60659c49","repo":"phalcon/cphalcon","slug":"router-cache-not-found-path","errorCode":null,"errorMessage":"Router cache not found: {path}","messagePattern":"Router cache not found: (.+?)","errorType":"exception","errorClass":"Phalcon\\Mvc\\Router\\Exception","httpStatus":null,"severity":"error","filePath":"phalcon/Mvc/Router.zep","lineNumber":952,"sourceCode":"\n        if !rename(tmpPath, path) {\n            this->phpUnlink(tmpPath);\n            throw new Exception(\"Failed to commit router cache: \" . path);\n        }\n    }\n\n    /**\n     * File-shaped helper around loadDispatcherFromArray(). Includes the\n     * file (opcache-friendly) and forwards the return value.\n     *\n     * @throws \\Phalcon\\Mvc\\Router\\Exception\n     */\n    public function loadDispatcher( string path) -> void\n    {\n        var dump;\n\n        if !this->phpFileExists(path) {\n            throw new Exception(\"Router cache not found: \" . path);\n        }\n\n        let dump = require path;\n\n        if typeof dump !== \"array\" {\n            throw new Exception(\n                \"Router cache is corrupt or invalid (expected array, got \" . gettype(dump) . \"): \" . path\n            );\n        }\n\n        this->loadDispatcherFromArray(dump);\n    }\n\n    /**\n     * Cache-instance convenience wrapper. On cache hit, restores the\n     * dispatcher immediately. On miss, defers cache population until the\n     * next handle() completes - at which point buildDispatcherDump() is\n     * written to the cache key.","sourceCodeStart":934,"sourceCodeEnd":970,"githubUrl":"https://github.com/phalcon/cphalcon/blob/b7419de9cd0a8a3f48441ead84c9f8415d463e25/phalcon/Mvc/Router.zep#L934-L970","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Generate the cache before loading: call buildRoutes($router)->dumpDispatcher($path) during deploy/build, then loadDispatcher($path) at runtime","Guard with file_exists($path) and fall back to building routes dynamically on miss","Use absolute paths computed from a single root so CLI and web resolve the same file","Ensure the cache file is present on every node/image that will load it"],"exampleFix":"// before\n$router->loadDispatcher($cachePath); // file never generated -> throws\n\n// after: build-on-miss pattern\nif (!file_exists($cachePath)) {\n    buildRoutes($router)->dumpDispatcher($cachePath);\n}\n$router->loadDispatcher($cachePath);","handlingStrategy":"validation","validationCode":"if (!is_file($cachePath)) {\n    buildRoutes($router)->dumpDispatcher($cachePath); // build on first run\n}\n$router->loadDispatcher($cachePath);","typeGuard":null,"tryCatchPattern":"try {\n    $router->loadDispatcher($cachePath);\n} catch (\\Phalcon\\Mvc\\Router\\Exception $e) {\n    buildRoutes($router); // fall back to dynamic routes this request\n    // optionally schedule a rebuild\n}","preventionTips":["Make cache generation an explicit deploy/build step so runtime loads always find the file","Use one absolute-path constant for the cache in both CLI (dump) and web (load) contexts","Distribute the generated cache to every node/container image that loads it"],"tags":["phalcon","router","caching","missing-file"],"backgroundTag":"cache-file-missing","analyzedSha":"b7419de9cd0a8a3f48441ead84c9f8415d463e25","analyzedAt":"2026-08-21T06:21:18.811Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}