symfony/routing · error · LogicException

Collection " " with locale " " is missing a corresponding…

Error message

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

What it means

Inverse of error 38: when a parent collection has locale prefixes, a child prefix array may not introduce locales the parent lacks. prefix() throws LogicException naming the collection, the offending locale, and the parent relationship.

Solutions

Add the missing locale to the parent collection's prefix array
Or drop the extra locale from the child prefix
Keep locale key sets synchronized between nested collections

Example fix

// before
$root = $collection->collection('app')->prefix(['en' => '/en']);
$root->prefix(['en' => '/en', 'de' => '/de']);
// after
$root->prefix(['en' => '/en', 'de' => '/de']); // parent now has de too
$root->prefix(['en' => '/en', 'de' => '/de']);

Defensive patterns

Strategy: validation

Validate before calling

$extra = array_diff_key($childPrefix, $parentPrefixes); if ($extra) { /* add locales to parent prefix first */ }

Type guard

function childLocalesSupported(array $parent, array $child): bool { return !array_diff_key($child, $parent); }

Try / catch

try { $routes = $loader->load($file); } catch (\LogicException $e) { if (str_contains($e->getMessage(), 'missing a corresponding prefix')) { /* add locale to parent prefix */ } throw $e; }

Prevention

Add new locales to the root collection prefix before children
Share locale constants across parent/child prefix builders
CI route-loading smoke test to catch locale drift

When it happens

Trigger: Child ->prefix(['en' => '/en', 'de' => '/de']) while the parent collection prefix only defines ['en' => '/en'] — 'de' has no parent prefix.

Common situations: Adding a new locale only to a sub-collection; inconsistent locale sets between parent and child collection prefixes in localized route trees.

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

Appendix: source

Thrown at Loader/Configurator/CollectionConfigurator.php:90

     * Sets the prefix to add to the path of all child routes.
     *
     * @param string|array $prefix the prefix, or the localized prefixes
     *
     * @return $this
     */
    final public function prefix(string|array $prefix, bool $trailingSlashOnRoot = true): static
    {
        $this->trailingSlashOnRoot = $trailingSlashOnRoot;

        if (\is_array($prefix)) {
            if (null === $this->parentPrefixes) {
                // no-op
            } elseif ($missing = array_diff_key($this->parentPrefixes, $prefix)) {
                throw new \LogicException(\sprintf('Collection "%s" is missing prefixes for locale(s) "%s".', $this->name, implode('", "', array_keys($missing))));
            } else {
                foreach ($prefix as $locale => $localePrefix) {
                    if (!isset($this->parentPrefixes[$locale])) {
                        throw new \LogicException(\sprintf('Collection "%s" with locale "%s" is missing a corresponding prefix in its parent collection.', $this->name, $locale));
                    }

                    $prefix[$locale] = $this->parentPrefixes[$locale].$localePrefix;
                }
            }
            $this->prefixes = $prefix;
            $this->route->setPath('/');
        } else {
            $this->prefixes = null;
            $this->route->setPath($prefix);
        }

        return $this;
    }

    /**
     * Sets the host to use for all child routes.
     *

View on GitHub (pinned to 83fa223250)