symfony/routing · error · InvalidArgumentException

Invalid characters found in deprecation template.

Error message

Invalid characters found in deprecation template.

What it means

Alias::setDeprecated() validates the deprecation message template because it is injected into compiled PHP/doc comments of generated containers. This error means the template contains characters (newlines, carriage returns, or the comment terminator '*/') that would break or exploit the generated code structure.

Solutions

1. Remove all newline/carriage-return characters and any '*/' sequence from the message template.
2. Collapse the message to a single line, e.g. str_replace(["\r","\n"], ' ', $message).
3. Keep the required '%alias_id%' placeholder in the template to avoid the follow-up error.
4. If the message comes from user/config input, sanitize it before passing to setDeprecated().

Example fix

// before
$alias->setDeprecated('acme/pkg', '2.0', "The service is deprecated.\nUse %alias_id% instead.");
// after
$alias->setDeprecated('acme/pkg', '2.0', 'The service is deprecated. Use %alias_id% instead.');

if (preg_match('#[\r\n]|\*/#', $message) || !str_contains($message, '%alias_id%')) {
    throw new InvalidArgumentException('Deprecation template must be single-line and contain %alias_id%.');
}

function isValidDeprecationTemplate(string $m): bool { return $m === '' || (!preg_match('#[\r\n]|\*/#', $m) && str_contains($m, '%alias_id%')); }

try { $alias->setDeprecated($pkg, $ver, $tpl); } catch (InvalidArgumentException $e) { /* log & use default template */ }

When it happens

Trigger: Calling setDeprecated() on a Symfony DI Alias with a $message containing '\n', '\r', or '*/'.

Common situations: Building a deprecation message by interpolating a multi-line doc comment, pasting a template containing a comment close sequence, or programmatically joining messages with newlines.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• The deprecation template must contain the "%alias_id%"…
• 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/f9ac1b509fee0c0a. Report an issue: GitHub.

Appendix: source

Thrown at Alias.php:59

        return $this->id;
    }

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

View on GitHub (pinned to 83fa223250)