symfony/routing · error · InvalidArgumentException

The deprecation template must contain the "%alias_id%"…

Error message

The deprecation template must contain the "%alias_id%" placeholder.

What it means

When marking an alias deprecated, the message template must include the '%alias_id%' placeholder, which the compiler replaces with the actual alias id at dump time. This error means the placeholder is missing, so the generated deprecation trigger could not reference the alias.

Solutions

1. Add '%alias_id%' to the deprecation template.
2. Use the default template style: 'The "%alias_id%" alias is deprecated. ...'
3. If you want no custom message, pass '' instead of a template without the placeholder.

Example fix

// before
$alias->setDeprecated('acme/pkg', '2.0', 'This alias is deprecated.');
// after
$alias->setDeprecated('acme/pkg', '2.0', 'The "%alias_id%" alias is deprecated.');

if ('' !== $tpl && !str_contains($tpl, '%alias_id%')) {
    throw new InvalidArgumentException('Template must contain %alias_id%.');
}

function hasAliasIdPlaceholder(string $m): bool { return $m === '' || str_contains($m, '%alias_id%'); }

try { $alias->setDeprecated($pkg, $ver, $tpl); } catch (InvalidArgumentException $e) { $alias->setDeprecated($pkg, $ver, 'The "%alias_id%" alias is deprecated.'); }

When it happens

Trigger: Calling setDeprecated() with a non-empty $message that does not contain the literal string '%alias_id%'.

Common situations: Writing a custom deprecation message by hand and forgetting the placeholder; upgrading Symfony where templates previously without placeholders are now rejected.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Invalid characters found in deprecation template.
• Using "%% %%" is not allowed in routing configuration.
• The container parameter
• The container parameter
• Unable to generate a URL for the named route

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

Appendix: source

Thrown at Alias.php:63

     * Whether this alias is deprecated, that means it should not be referenced anymore.
     *
     * @param string $package The name of the composer package that is triggering the deprecation
     * @param string $version The version of the package that introduced the deprecation
     * @param string $message The deprecation message to use
     *
     * @return $this
     *
     * @throws InvalidArgumentException when the message template is invalid
     */
    public function setDeprecated(string $package, string $version, string $message): static
    {
        if ('' !== $message) {
            if (preg_match('#[\r\n]|\*/#', $message)) {
                throw new InvalidArgumentException('Invalid characters found in deprecation template.');
            }

            if (!str_contains($message, '%alias_id%')) {
                throw new InvalidArgumentException('The deprecation template must contain the "%alias_id%" placeholder.');
            }
        }

        $this->deprecation = [
            'package' => $package,
            'version' => $version,
            'message' => $message ?: 'The "%alias_id%" route alias is deprecated. You should stop using it, as it will be removed in the future.',
        ];

        return $this;
    }

    public function isDeprecated(): bool
    {
        return (bool) $this->deprecation;
    }

    /**

View on GitHub (pinned to 83fa223250)