slimphp/Slim · error · RuntimeException

Named route does not exist for name: %s

Error message

Named route does not exist for name: %s

What it means

RouteCollector::getNamedRoute() is the lookup behind RouteParser::urlFor()/fullUrlFor() and every 'generate URL by name' API. It checks the routesByName cache, then falls back to a linear scan of all registered routes; if no route carries the requested name it throws this RuntimeException. It means that, at the moment of the call, no route registered via ->setName() (or ->setName() on the result of map/get/post/...) matches the given string exactly.

Source

Thrown at Slim/Routing/RouteCollector.php:213

    public function getNamedRoute(string $name): RouteInterface
    {
        if (isset($this->routesByName[$name])) {
            $route = $this->routesByName[$name];
            if ($route->getName() === $name) {
                return $route;
            }

            unset($this->routesByName[$name]);
        }

        foreach ($this->routes as $route) {
            if ($name === $route->getName()) {
                $this->routesByName[$name] = $route;
                return $route;
            }
        }

        throw new RuntimeException('Named route does not exist for name: ' . $name);
    }

    /**
     * {@inheritdoc}
     */
    public function lookupRoute(string $identifier): RouteInterface
    {
        if (!isset($this->routes[$identifier])) {
            throw new RuntimeException('Route not found, looks like your route cache is stale.');
        }
        return $this->routes[$identifier];
    }

    /**
     * {@inheritdoc}
     */
    public function group(string $pattern, $callable): RouteGroupInterface
    {

View on GitHub (pinned to 80900fb39c)

Solutions

1. Verify the name matches exactly (case-sensitive) the value passed to ->setName() on that route
2. Ensure the route definition file is loaded before urlFor() runs (check require/include order in bootstrap)
3. If route caching is enabled, delete the cache file after adding or renaming routes so it is rebuilt
4. Guard call sites with a hasNamedRoute() check over $app->getRouteCollector()->getRoutes() and fail with a clear message listing known names

Example fix

// before
$url = $routeParser->urlFor('user.profil', ['id' => 42]); // typo, name never registered

// after
$app->get('/user/{id:[0-9]+}', UserProfileAction::class)->setName('user.profile');
$url = $routeParser->urlFor('user.profile', ['id' => 42]);

function hasNamedRoute(Slim\Routing\RouteCollector $collector, string $name): bool
{
    foreach ($collector->getRoutes() as $route) {
        if ($route->getName() === $name) {
            return true;
        }
    }
    return false;
}

// before generating:
if (!hasNamedRoute($app->getRouteCollector(), 'user.profile')) {
    throw new RuntimeException("Route name 'user.profile' is not registered — check ->setName() and route loading order");
}
$url = $app->getRouteCollector()->getRouteParser()->urlFor('user.profile', ['id' => 42]);

try {
    $url = $routeParser->urlFor($name, $data);
} catch (RuntimeException $e) {
    // message contains the unknown name; log with known names for quick diagnosis
    $log->warning($e->getMessage(), ['known' => array_map(fn($r) => $r->getName(), $collector->getRoutes())]);
    $url = '/'; // or rethrow as a domain-specific exception with context
}

When it happens

Trigger: Calling $routeParser->urlFor('user.profile', [...]) (from RouteContext::fromRequest($request)->getRouteParser() or $app->getRouteCollector()->getRouteParser()) with a name that was never set, is misspelled, or has different casing. Also triggered when the route file defining the name has not been loaded yet, or when a route cache file was generated before the named route existed (lookup scans in-memory routes only, not the dispatcher cache).

Common situations: Typos and case mismatches ('UserProfile' vs 'user.profile'); renaming a route in definitions but not at call sites; URL generation happening in middleware or bootstrap before all route definition files are required; stale route cache after adding new named routes; expecting group patterns to auto-prefix route names (Slim does not — names must be set explicitly per route); porting from Slim 3 pathFor() with old names.

Related errors

• No base path defined.
• Missing data for URL segment: %s
• Route collector cache file directory `%s` is not writable
• Route not found, looks like your route cache is stale.
• Cannot create RouteContext before routing has been completed

AI-assisted analysis of slimphp/Slim@80900fb39c (2026-08-21). Data as JSON: /api/errors/cc169b5fc4307273. Report an issue: GitHub.