{"record":{"id":"a7dee0d6c0891683","repo":"flarum/framework","slug":"route-name-already-exists","errorCode":null,"errorMessage":"Route $name already exists","messagePattern":"Route \\$name already exists","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"framework/core/src/Http/RouteCollection.php","lineNumber":61,"sourceCode":"    public function put(string $path, string $name, callable|string $handler): self\n    {\n        return $this->addRoute('PUT', $path, $name, $handler);\n    }\n\n    public function patch(string $path, string $name, callable|string $handler): self\n    {\n        return $this->addRoute('PATCH', $path, $name, $handler);\n    }\n\n    public function delete(string $path, string $name, callable|string $handler): self\n    {\n        return $this->addRoute('DELETE', $path, $name, $handler);\n    }\n\n    public function addRoute(string $method, string $path, string $name, callable|string $handler): self\n    {\n        if (isset($this->routes[$name])) {\n            throw new \\RuntimeException(\"Route $name already exists\");\n        }\n\n        $this->routes[$name] = $this->pendingRoutes[$name] = compact('method', 'path', 'handler');\n\n        return $this;\n    }\n\n    public function removeRoute(string $name): self\n    {\n        unset($this->routes[$name], $this->pendingRoutes[$name]);\n\n        return $this;\n    }\n\n    protected function applyRoutes(): void\n    {\n        foreach ($this->pendingRoutes as $name => $route) {\n            $routeDatas = $this->routeParser->parse($route['path']);","sourceCodeStart":43,"sourceCodeEnd":79,"githubUrl":"https://github.com/flarum/framework/blob/4b939f685389bfe8a380e9e28ddf305a1c66950c/framework/core/src/Http/RouteCollection.php#L43-L79","documentation":"Flarum's RouteCollection stores routes keyed by unique name. addRoute() throws this RuntimeException when you try to register a route whose $name is already taken, because duplicate names would make reverse URL generation (getPath) ambiguous. It is an intentional registration-time guard, not a runtime failure.","triggerScenarios":"Calling addRoute(), get(), post(), put(), patch() or delete() twice with the same route name on the same RouteCollection — e.g. two extensions registering a route named 'index', or re-running a route registration closure on every request without a fresh collection.","commonSituations":"Two extensions both registering a default frontend route with the same name; copy-pasted route registration code where the second call forgot to change the name; boot code executed twice due to a service provider being registered multiple times.","solutions":["Rename one of the routes so each name is unique across the application.","Call removeRoute($name) before re-registering if overwriting is intended.","Check which extension(s) register the colliding name (search for the route name string in registered extensions).","Ensure route registration code runs only once (e.g. not inside a loop or a repeatedly-invoked boot hook)."],"exampleFix":"// before\n$routes->get('/forum', 'index', IndexHandler::class);\n$routes->get('/', 'index', HomeHandler::class); // RuntimeException\n// after\n$routes->get('/forum', 'forum.index', IndexHandler::class);\n$routes->get('/', 'home.index', HomeHandler::class);","handlingStrategy":"validation","validationCode":"if (array_key_exists($name, $routes->getRoutes())) {\n    $routes->removeRoute($name); // or skip/throw your own clearer error\n}\n$routes->get($path, $name, $handler);","typeGuard":"function routeNameIsFree(RouteCollection $routes, string $name): bool {\n    return !array_key_exists($name, $routes->getRoutes());\n}","tryCatchPattern":"try {\n    $routes->get($path, $name, $handler);\n} catch (\\RuntimeException $e) {\n    if (str_contains($e->getMessage(), 'already exists')) {\n        $routes->removeRoute($name)->get($path, $name, $handler);\n    } else {\n        throw $e;\n    }\n}","preventionTips":["Prefix route names with the extension id (e.g. 'acme.feature') to guarantee uniqueness.","Centralize route name strings in constants.","Never run route registration code twice per request."],"tags":["php","routing","duplicate-registration","flarum"],"backgroundTag":"file-already-exists","analyzedSha":"4b939f685389bfe8a380e9e28ddf305a1c66950c","analyzedAt":"2026-09-15T18:09:20.879Z","contentChangedAt":"2026-09-15T18:09:20.879Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}