symfony/routing · error · InvalidArgumentException

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

Error message

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

What it means

When applying localized hosts, HostTrait::addHost() requires every locale used by a child route to have a matching host defined in the parent collection's 'host' locale map. If a child route declares a locale whose host is absent from $hosts, an InvalidArgumentException is thrown so misconfigured localized hosts fail fast.

Solutions

Add the missing locale to the parent's host map: ->host(['en' => 'en.example.com', 'fr' => 'fr.example.com']).
Fix locale key mismatches (typos, case, subtags) between the child route and parent hosts array.
If the locale should not be host-localized, remove it from the child route's localized paths.

Example fix

// before
$collection->host(['en' => 'en.example.com'])
    ->route('home', ['en' => '/', 'fr' => '/accueil']);
// after
$collection->host(['en' => 'en.example.com', 'fr' => 'fr.example.com'])
    ->route('home', ['en' => '/', 'fr' => '/accueil']);

Defensive patterns

Strategy: validation

Validate before calling

$missing = array_diff(array_keys($routePaths), array_keys($parentHosts));
if ($missing) { throw new \LogicException('Add hosts for locales: ' . implode(',', $missing)); }

Try / catch

try { $collection->host($hosts)->route(...); } catch (\InvalidArgumentException $e) { /* log which locale/host pair is missing */ }

Prevention

Keep a single canonical locale list and derive both host and prefix maps from it.
Verify every child route locale exists in the parent host map before import.
Watch locale subtag mismatches (fr vs fr-FR).

When it happens

Trigger: Calling ->route()/->collection() with localized paths for a locale not present in the parent's ->host(['en' => ..., 'fr' => ...]) map, i.e. a route locale key missing from the parent hosts array.

Common situations: Adding a new language to route paths but forgetting to add the corresponding host entry in the parent collection; typos in locale codes ('fr-FR' vs 'fr'); mixing host- and prefix-based localization inconsistently.

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

Appendix: source

Thrown at Loader/Configurator/Traits/HostTrait.php:42

            $routes->setHost($hosts ?: '');

            return;
        }

        foreach ($routes->all() as $name => $route) {
            if (null === $locale = $route->getDefault('_locale')) {
                $priority = $routes->getPriority($name) ?? 0;
                $routes->remove($name);
                foreach ($hosts as $locale => $host) {
                    $localizedRoute = clone $route;
                    $localizedRoute->setDefault('_locale', $locale);
                    $localizedRoute->setRequirement('_locale', preg_quote($locale));
                    $localizedRoute->setDefault('_canonical_route', $name);
                    $localizedRoute->setHost($host);
                    $routes->add($name.'.'.$locale, $localizedRoute, $priority);
                }
            } elseif (!isset($hosts[$locale])) {
                throw new \InvalidArgumentException(\sprintf('Route "%s" with locale "%s" is missing a corresponding host in its parent collection.', $name, $locale));
            } else {
                $route->setHost($hosts[$locale]);
                $route->setRequirement('_locale', preg_quote($locale));
                $routes->add($name, $route, $routes->getPriority($name) ?? 0);
            }
        }
    }
}

View on GitHub (pinned to 83fa223250)