phalcon/cphalcon · error · Phalcon\Mvc\Url\Exceptions\RouteNotFound

Cannot obtain a route using the name '{routeName}'

Error message

Cannot obtain a route using the name '{routeName}'

What it means

Url::get(['for' => $name]) resolves the name through Router::getRouteByName() (phalcon/Mvc/Url.zep:176). If the router returns nothing for that name — no route was ever named $routeName — RouteNotFound is thrown with the offending name interpolated into the message. Named-route generation requires routes explicitly named via setName()/['name' => ...] in the loaded definition.

Source

Thrown at phalcon/Mvc/Url.zep:176

                if unlikely typeof container != "object" {
                    throw new RouterServiceUnavailable();
                }

                if unlikely !container->has("router") {
                    throw new RouterServiceUnavailable();
                }

                let router       = <RouterInterface> container->getShared("router"),
                    this->router = router;
            }

            /**
             * Every route is uniquely differenced by a name
             */
            let route = <RouteInterface> router->getRouteByName(routeName);

            if unlikely typeof route != "object" {
                throw new RouteNotFound(routeName);
            }

            /**
             * Replace the patterns by its variables
             */
            let uri = phalcon_replace_paths(
                route->getPattern(),
                route->getReversedPaths(),
                uri
            );

            /**
             * If the route has a hostname restriction, prepend it as a
             * protocol-relative URL so the generated link works under
             * both HTTP and HTTPS.  The baseUri is not prepended in this
             * case because the hostname already provides the authority.
             */
            let hostname = route->getHostname();

View on GitHub (pinned to b7419de9cd)

Solutions

1. Verify the exact name: $router->getRouteByName('posts-show') should return a RouteInterface before Url::get() is called
2. Add ->setName('posts-show') (or 'name' in the array definition) to the intended route
3. Ensure the routes are actually mounted/loaded before URL generation (check route order in bootstrap and module definitions)

Example fix

// before
$router->add('/post/{id}', ['controller' => 'posts', 'action' => 'show']);
$url->get(['for' => 'post-show', 'id' => 7]); // route never named

// after
$router->add('/post/{id}', ['controller' => 'posts', 'action' => 'show'])
       ->setName('post-show');
$url->get(['for' => 'post-show', 'id' => 7]);

if ($router->getRouteByName($routeName) === null) {
    throw new \InvalidArgumentException("No route named '{$routeName}' is registered");
}

use Phalcon\Mvc\Url\Exceptions\RouteNotFound;
try {
    $link = $url->get(['for' => $routeName] + $params);
} catch (RouteNotFound $e) {
    $link = $url->get('/fallback/path', $params); // or log and rethrow
}

When it happens

Trigger: Typo between 'for' value and the ->setName() value; routes defined in a module/controller that was never mounted; generating URLs before the routes file was loaded into the router; mixed case ('Posts-show' vs 'posts-show').

Common situations: Route defined but never named (names are not auto-generated); route definitions in a not-yet-loaded module or deferred provider; renaming a route during refactor while templates/Volt {{ url() }} calls still use the old name; routes added via annotations where the annotation loader did not run.

Related errors

• It's necessary to define the route name with the parameter '
• A dependency injection container is required to access the '
• Arguments must be an array or string, {type} given
• Before-Match callback is not callable in matched route '{pat
• Before-Match callback is not callable in matched route '{pat

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