symfony/routing · error · LogicException

Route " " with locale " " is missing a corresponding prefix…

Error message

Route "%s" with locale "%s" is missing a corresponding prefix in its parent collection.

What it means

The inverse check of the missing-locales case: the route's path array contains a locale key that the parent collection's prefix map does not define. createLocalizedRoute() throws a LogicException because it cannot build a full localized path without the parent prefix for that locale.

Solutions

Add the missing locale to the parent's prefix map so it matches the route's locale keys.
Remove the extra locale from the route's path array.
Align locale codes exactly (including region subtags) between prefix and route arrays.

Example fix

// before
->prefix(['en' => '/en'])
    ->route('home', ['en' => '/', 'fr' => '/accueil']);
// after
->prefix(['en' => '/en', 'fr' => '/fr'])
    ->route('home', ['en' => '/', 'fr' => '/accueil']);

Defensive patterns

Strategy: validation

Validate before calling

$extra = array_diff_key($paths, $prefixes);
if ($extra) { throw new \LogicException('Parent prefixes missing for: ' . implode(',', array_keys($extra))); }

Try / catch

try { $cfg->add($name, $paths); } catch (\LogicException $e) { /* add missing prefix or drop the locale */ }

Prevention

Derive route path arrays from the same locale keys used in prefix().
Audit route locale keys against the parent prefix map in CI.
Avoid hardcoding locale arrays per route.

When it happens

Trigger: Passing ['en' => '/', 'fr' => '/accueil'] to a route whose parent has only ->prefix(['en' => '/en']) (or a non-localized prefix); locale key typos ('fr-FR' in the route vs 'fr' in the prefix).

Common situations: Reusing route definitions across collections where one has full locale prefixes and another does not; adding a locale to a route before updating the parent prefix map.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

AI-assisted analysis of symfony/routing@83fa223250 (2026-09-14). Data as JSON: /api/errors/db3f59b969166f83. Report an issue: GitHub.

Appendix: source

Thrown at Loader/Configurator/Traits/LocalizedRouteTrait.php:44

     * Creates one or many routes.
     *
     * @param string|array $path the path, or the localized paths of the route
     */
    final protected function createLocalizedRoute(RouteCollection $collection, string $name, string|array $path, string $namePrefix = '', ?array $prefixes = null): RouteCollection
    {
        $paths = [];

        $routes = new RouteCollection();

        if (\is_array($path)) {
            if (null === $prefixes) {
                $paths = $path;
            } elseif ($missing = array_diff_key($prefixes, $path)) {
                throw new \LogicException(\sprintf('Route "%s" is missing routes for locale(s) "%s".', $name, implode('", "', array_keys($missing))));
            } else {
                foreach ($path as $locale => $localePath) {
                    if (!isset($prefixes[$locale])) {
                        throw new \LogicException(\sprintf('Route "%s" with locale "%s" is missing a corresponding prefix in its parent collection.', $name, $locale));
                    }

                    $paths[$locale] = $prefixes[$locale].$localePath;
                }
            }
        } elseif (null !== $prefixes) {
            foreach ($prefixes as $locale => $prefix) {
                $paths[$locale] = $prefix.$path;
            }
        } else {
            $routes->add($namePrefix.$name, $route = $this->createRoute($path));
            $collection->add($namePrefix.$name, $route);

            return $routes;
        }

        foreach ($paths as $locale => $path) {
            $routes->add($name.'.'.$locale, $route = $this->createRoute($path));

View on GitHub (pinned to 83fa223250)