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

Router cache is corrupt or invalid (expected array, got {get

Error message

Router cache is corrupt or invalid (expected array, got {gettype}): {path}

What it means

loadDispatcher() include/requires the cache file and expects it to return an array (files written by dumpDispatcher() start with '<?php return array(...);'). If require yields anything else - a scalar, null, or even PHP output captured as a non-array - the file is declared corrupt or invalid, with the actual gettype() included in the message.

Source

Thrown at phalcon/Mvc/Router.zep:958

    /**
     * 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.
     *
     * @throws \Phalcon\Mvc\Router\Exception
     */
    public function useCache(<CacheAdapterInterface> cache,  string key = "phalcon.router.dispatcher") -> void
    {
        var stored;

View on GitHub (pinned to b7419de9cd)

Solutions

1. Delete the corrupt file and regenerate it with dumpDispatcher()
2. Never hand-edit generated cache files; change route definitions and re-dump instead
3. Treat 'corrupt or invalid' as a cache-miss in a wrapper: catch Phalcon\Mvc\Router\Exception, unlink the file, rebuild routes dynamically, re-dump
4. Verify with a quick check that require returns an array before handing it to the router (see validation pattern)

Example fix

// before
$router->loadDispatcher($path); // file returns a scalar / executes code -> throws

// after: self-healing load with regenerate-on-corruption
try {
    $router->loadDispatcher($path);
} catch (\Phalcon\Mvc\Router\Exception $e) {
    @unlink($path);
    buildRoutes($router)->dumpDispatcher($path);
    $router->loadDispatcher($path);
}

// Cheap pre-check when reusing a dump you did not just generate
$dump = require $path;
if (!is_array($dump)) {
    unlink($path);
    buildRoutes($router)->dumpDispatcher($path);
    $dump = require $path;
}
$router->loadDispatcherFromArray($dump);

function returnsArray(string $phpFile): bool
{
    $value = include $phpFile; // side-effect free for well-formed dumps
    return is_array($value);
}

try {
    $router->loadDispatcher($path);
} catch (\Phalcon\Mvc\Router\Exception $e) {
    @unlink($path);                          // quarantined corrupt file
    buildRoutes($router)->dumpDispatcher($path);
    $router->loadDispatcher($path);
}

When it happens

Trigger: The cache file was hand-edited and no longer returns an array; a truncated/partially written file (crash before atomic rename, or someone edited in place); a file at that path that is plain PHP code executing side effects instead of returning data; output before the return statement turning the include result into echoed text; wrong file entirely (a config PHP file) sitting at the cache path.

Common situations: Manual 'fixes' to generated caches; deploy pipelines that copy files mid-write; code that points the loader at a hand-written bootstrap file; whitespace/BOM or debug statements injected above the return by tooling.

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/348fa3c217ada1b6. Report an issue: GitHub.