symfony/routing · error · InvalidArgumentException

The routing file " " must specify the attribute "version"…

Error message

The routing file "%s" must specify the attribute "version" of the "deprecated" option for "%s".

What it means

A 'deprecated' option on a route alias must include a 'version' attribute stating the release in which the alias was deprecated. ContentLoaderTrait::validateAlias() throws InvalidArgumentException when 'deprecated' omits 'version', since the deprecation message must tell users which version started the deprecation.

Solutions

1. Add the 'version' attribute, e.g. version: '2.0', alongside 'package'
2. Remove the 'deprecated' key if no deprecation is intended
3. Validate that both package and version exist whenever editing alias deprecations

Example fix

# before
app_new:
    alias: app_old
    deprecated:
        package: 'acme/awesome-package'

# after
app_new:
    alias: app_old
    deprecated:
        package: 'acme/awesome-package'
        version: '2.0'

if (isset($config['deprecated']) && !isset($config['deprecated']['version'])) {
    throw new \LogicException('deprecated option requires a "version" attribute.');
}

function hasDeprecationVersion(array $config): bool { return !isset($config['deprecated']) || isset($config['deprecated']['version']); }

try { $collection = $loader->load($file, 'yaml'); } catch (\InvalidArgumentException $e) { /* add version to deprecated block */ }

When it happens

Trigger: A routing alias entry with deprecated: { package: 'acme/pkg' } — 'package' given but 'version' missing.

Common situations: Hand-written deprecation blocks where the version was forgotten; generated configs with incomplete metadata; copy-paste of examples that only showed 'package'.

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

• The routing file " " must specify the attribute "package"…
• The routing file " " must not specify other keys than…
• Parameter " " for route " " must match " " (" " given) to…
• Parameters for route
• Route aliases cannot be used on non-invokable class

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

Appendix: source

Thrown at Loader/ContentLoaderTrait.php:258

     * Validates that an alias definition only carries the `alias` and `deprecated` keys.
     *
     * @throws \InvalidArgumentException If one of the provided config keys is not supported,
     *                                   something is missing or the combination is nonsense
     */
    private function validateAlias(array $config, string $name, string $path): void
    {
        foreach ($config as $key => $value) {
            if (!\in_array($key, ['alias', 'deprecated'], true)) {
                throw new \InvalidArgumentException(\sprintf('The routing file "%s" must not specify other keys than "alias" and "deprecated" for "%s".', $path, $name));
            }

            if ('deprecated' === $key) {
                if (!isset($value['package'])) {
                    throw new \InvalidArgumentException(\sprintf('The routing file "%s" must specify the attribute "package" of the "deprecated" option for "%s".', $path, $name));
                }

                if (!isset($value['version'])) {
                    throw new \InvalidArgumentException(\sprintf('The routing file "%s" must specify the attribute "version" of the "deprecated" option for "%s".', $path, $name));
                }
            }
        }
    }
}

View on GitHub (pinned to 83fa223250)