What causes "Route $name not found" in flarum/framework?

Verify the exact route name by inspecting getRoutes() or the registration code (search for the name string).

flarum/framework · error · RuntimeException

Route $name not found

Error message

Route $name not found

What it means

RouteCollection::getPath() throws this RuntimeException when the requested route name does not exist in the collection's reverse lookup table ($this->reverse). Route names must be registered first via addRoute()/get()/etc. before URLs can be generated from them.

Solutions

Verify the exact route name by inspecting getRoutes() or the registration code (search for the name string).
Fix the name typo or update the caller to the renamed route.
Register the missing route if it genuinely should exist.
Ensure you call getPath() on the same RouteCollection instance where the route was registered.

Example fix

// before
$url = $routes->getPath('userr.profile'); // route registered as 'user.profile'
// after
$url = $routes->getPath('user.profile');

Defensive patterns

Strategy: try-catch

Validate before calling

if (!array_key_exists($name, $routes->getRoutes())) {
    // route unknown: log and skip URL generation
    return null;
}
$url = $routes->getPath($name, $parameters);

Type guard

function routeExists(RouteCollection $routes, string $name): bool {
    return array_key_exists($name, $routes->getRoutes());
}

Try / catch

try {
    $url = $routes->getPath($name, $parameters);
} catch (\RuntimeException $e) {
    if (str_contains($e->getMessage(), 'not found')) {
        $url = null; // or fallback URL
    } else {
        throw $e;
    }
}

Prevention

Define route names as class constants shared by registration and generation sites.
Grep for the name string in registration code before using it in getPath().
Remember each frontend (forum/admin/api) has its own RouteCollection.

When it happens

Trigger: Calling getPath('someName') where no route named 'someName' was ever registered — typically a typo in the route name, a route registered in a different frontend's RouteCollection, or a removed/renamed route still referenced in templates or controllers.

Common situations: Typo in the route name string; using a route registered for the forum frontend inside the admin frontend; an extension that provided the route was disabled or removed; route renamed in a framework upgrade while old references remain.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

AI-assisted analysis of flarum/framework@4b939f6853 (2026-09-15). Data as JSON: /api/errors/b510ffa4e0653f6a. Report an issue: GitHub.

Appendix: source

Thrown at framework/core/src/Http/RouteCollection.php:148

            // (which we don't care about here), or an array where the first element is the parameter name
            // and the second element is a regex into which the parameter value is inserted, if the parameter matches.
            foreach ($this->reverse[$name] as $parts) {
                foreach ($parts as $i => $part) {
                    if ($i > $maxMatches && is_array($part) && Arr::exists($parameters, $part[0])) {
                        $maxMatches = $i;
                        $matchingParts = $parts;
                    }
                }
            }

            $fixedParts = array_map(function ($part) use ($parameters, $name) {
                return $this->fixPathPart($part, $parameters, $name);
            }, $matchingParts);

            return '/'.ltrim(implode('', $fixedParts), '/');
        }

        throw new \RuntimeException("Route $name not found");
    }
}

View on GitHub (pinned to 4b939f6853)