symfony/routing · error · InvalidArgumentException

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

PrefixTrait::addPrefix() walks a route's localized paths and applies the parent collection's prefix per locale. When a route declares a locale that has no prefix in the parent's prefix array, it throws an InvalidArgumentException — same family as error 44 but at the import/collection level (parseImport path).

Solutions

Add the missing locale to the parent collection's prefix map.
Correct locale key typos in the route or import configuration.
Remove unsupported locales from the imported route definitions.

Example fix

// before
$collection->prefix(['en' => '/en'])->import('routes/');
// routes/ contains 'de' paths
// after
$collection->prefix(['en' => '/en', 'de' => '/de'])->import('routes/');

Defensive patterns

Strategy: validation

Validate before calling

foreach ($routeLocales as $locale) { if (!isset($parentPrefix[$locale])) { throw new \InvalidArgumentException("No prefix for {$locale}"); } }

Try / catch

try { $collection->prefix($prefix)->import($resource); } catch (\InvalidArgumentException $e) { /* fix prefix/locale mismatch in config */ }

Prevention

Define prefixes once from the master locale list.
Synchronize child route locales with the importing collection's prefix().
Add config linting that cross-checks locale keys.

When it happens

Trigger: Importing a collection whose routes use localized paths for locales not present in the parent ->prefix([...]) map; key mismatches between route locale keys and the prefix array.

Common situations: Config file imports where child route files were updated to a new locale but the parent's prefix() call wasn't; locale subtag mismatches ('de-AT' vs 'de').

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/e7d67bdff91df99d. Report an issue: GitHub.

Appendix: source

Thrown at Loader/Configurator/Traits/PrefixTrait.php:53

                if (null === $locale = $route->getDefault('_locale')) {
                    $priority = $routes->getPriority($name) ?? 0;
                    $routes->remove($name);
                    foreach ($aliases[$name] ?? [] as $aliasName) {
                        $routes->remove($aliasName);
                    }
                    foreach ($prefix as $locale => $localePrefix) {
                        $localizedRoute = clone $route;
                        $localizedRoute->setDefault('_locale', $locale);
                        $localizedRoute->setRequirement('_locale', preg_quote($locale));
                        $localizedRoute->setDefault('_canonical_route', $name);
                        $localizedRoute->setPath($localePrefix.(!$trailingSlashOnRoot && '/' === $route->getPath() ? '' : $route->getPath()));
                        $routes->add($name.'.'.$locale, $localizedRoute, $priority);
                        foreach ($aliases[$name] ?? [] as $aliasName) {
                            $routes->addAlias($aliasName.'.'.$locale, $name.'.'.$locale);
                        }
                    }
                } elseif (!isset($prefix[$locale])) {
                    throw new \InvalidArgumentException(\sprintf('Route "%s" with locale "%s" is missing a corresponding prefix in its parent collection.', $name, $locale));
                } else {
                    $route->setPath($prefix[$locale].(!$trailingSlashOnRoot && '/' === $route->getPath() ? '' : $route->getPath()));
                    $routes->add($name, $route, $routes->getPriority($name) ?? 0);
                }
            }

            return;
        }

        $routes->addPrefix($prefix);
        if (!$trailingSlashOnRoot) {
            $rootPath = (new Route(trim(trim($prefix), '/').'/'))->getPath();
            foreach ($routes->all() as $route) {
                if ($route->getPath() === $rootPath) {
                    $route->setPath(rtrim($rootPath, '/'));
                }
            }
        }

View on GitHub (pinned to 83fa223250)