phalcon/cphalcon · error · Phalcon\Mvc\Router\Exceptions\InvalidRouterFactoryConfig

RouterFactory::load requires an array or Phalcon\Config\Conf

Error message

RouterFactory::load requires an array or Phalcon\Config\ConfigInterface instance

What it means

RouterFactory::load() (and RouterFactory::newInstance(), which shares the same config path in phalcon/Mvc/Router/RouterFactory.zep) accepts either a plain PHP array or an object implementing Phalcon\Config\ConfigInterface. This throw fires at line 52 when you passed an object that is NOT a ConfigInterface instance, so the factory cannot call toArray() on it to normalize the config.

Source

Thrown at phalcon/Mvc/Router/RouterFactory.zep:52

 * );
 *```
 */
class RouterFactory
{
    /**
     * Builds a Router from a config array or ConfigInterface and loads routes.
     *
     * @param array|\Phalcon\Config\ConfigInterface config
     *
     * @return RouterInterface
     */
    public function load(var config) -> <RouterInterface>
    {
        var defaultRoutes, router;

        if typeof config === "object" {
            if !(config instanceof ConfigInterface) {
                throw new InvalidRouterFactoryConfig();
            }
            let config = config->toArray();
        }

        if typeof config !== "array" {
            throw new InvalidRouterFactoryConfig();
        }

        let defaultRoutes = true;
        if isset config["defaultRoutes"] {
            let defaultRoutes = (bool) config["defaultRoutes"];
        }

        let router = this->newInstance(defaultRoutes);
        router->loadFromConfig(config);

        return router;
    }

View on GitHub (pinned to b7419de9cd)

Solutions

1. Pass a plain array of route definitions instead of an object
2. If you have a Config object, ensure it is \Phalcon\Config\Config (implements ConfigInterface) or call ->toArray() before load()
3. For custom config classes, implement Phalcon\Config\ConfigInterface (toArray, path, merge, etc.)

Example fix

// before
$factory = new \Phalcon\Mvc\Router\RouterFactory();
$router = $factory->load(json_decode($json)); // stdClass -> InvalidRouterFactoryConfig

// after
$factory = new \Phalcon\Mvc\Router\RouterFactory();
$router = $factory->load(json_decode($json, true)); // plain array

if (!(is_array($config) || $config instanceof \Phalcon\Config\ConfigInterface)) {
    throw new \InvalidArgumentException('RouterFactory config must be array or ConfigInterface');
}

function acceptsRouterConfig(mixed $config): bool
{
    return is_array($config) || $config instanceof \Phalcon\Config\ConfigInterface;
}

try {
    $router = $factory->load($config);
} catch (\Phalcon\Mvc\Router\Exceptions\InvalidRouterFactoryConfig $e) {
    // normalize then retry once with the array form
    $router = $factory->load(is_object($config) && method_exists($config, 'toArray') ? $config->toArray() : []);
}

When it happens

Trigger: Calling (new \Phalcon\Mvc\Router\RouterFactory())->load($obj) where $obj is \stdClass (e.g. from json_decode()), ArrayObject, or a custom config class that does not implement Phalcon\Config\ConfigInterface.

Common situations: Migrating Phalcon 4 code to 5 where \Phalcon\Config moved to \Phalcon\Config\Config; passing json_decode() output without a true second argument; passing a domain object or collection instead of config; wrapping route config in a custom wrapper class.

Related errors

• loadFromConfig requires an array or Phalcon\Config\ConfigInt
• 'defaults' must be an array
• 'routes' must be an array
• 'groups' must be an array
• Route config entry is missing 'pattern'

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