symfony/routing · error · InvalidArgumentException

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

Error message

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

What it means

A 'deprecated' option on a route alias must include a 'package' attribute naming the composer package in which the alias is deprecated. ContentLoaderTrait::validateAlias() throws InvalidArgumentException when 'deprecated' is given without 'package', because deprecation notices need the package to attribute the notice correctly.

Solutions

1. Add the missing 'package' attribute, e.g. deprecated: { package: 'acme/pkg', version: '2.0' }
2. Remove the 'deprecated' key entirely if the alias is not meant to be deprecated
3. Also verify 'version' is present, since it is required too

Example fix

# before
app_new:
    alias: app_old
    deprecated:
        version: '2.0'

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

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

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

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

When it happens

Trigger: A routing alias entry with a 'deprecated' key whose value lacks the 'package' attribute, e.g. deprecated: { version: '2.0' } or deprecated: true-like scalars.

Common situations: Following older docs or a half-remembered deprecation syntax; hand-editing deprecation metadata and dropping one attribute; tooling generating partial deprecation blocks.

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 "version"…
• 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/1f5524673d569f6b. Report an issue: GitHub.

Appendix: source

Thrown at Loader/ContentLoaderTrait.php:254

        }
    }

    /**
     * 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)