twigphp/Twig · error · SyntaxError

The template references in a "use" statement must be a…

Error message

The template references in a "use" statement must be a string.

What it means

The {% use %} statement requires its template reference to be a literal string (ConstantExpression). Dynamic template names (variables, expressions) cannot be used because imports are resolved at compile time for horizontal reuse.

Solutions

1. Replace the dynamic name with a literal string, e.g. '{% use "blocks/layout.html.twig" %}'
2. Use {% include %} or {% import %} with a dynamic name if runtime selection is required
3. Handle the variation with an if/else around multiple literal {% use %} statements (in separate branches/templates)

Example fix

// before
{% use templates.get('blocks') %}
// after
{% use "blocks/default.html.twig" %}

// use statements need string literals
foreach (tokenizeTemplateUseStatements($src) as $useExpr) {
    if (!preg_match('/^\s*([\'\"]).+\1\s*$/', $useExpr)) {
        throw new InvalidArgumentException('use requires a quoted template string.');
    }
}

try {
    $twig->render($template, $ctx);
} catch (SyntaxError $e) {
    if (str_contains($e->getMessage(), '"use" statement')) {
        // replace dynamic use with include/import or literal
    }
    throw $e;
}

When it happens

Trigger: Writing '{% use some_var %}' or '{% use templates["blocks"] %}' — parse throws when parseExpression() returns anything other than a ConstantExpression.

Common situations: Trying to parameterize which trait/block template is imported based on config or request; confusing {% use %} with {% include %}, which does accept dynamic names.

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.

Related errors

• Unexpected character
• The variadic argument
• The variadic argument
• When using set, you must have the same number of variables…
• When using set with a block, you cannot have a multi-target.

AI-assisted analysis of twigphp/Twig@a414c3a491 (2026-09-13). Data as JSON: /api/errors/ab0367f07fe4f2d1. Report an issue: GitHub.

Appendix: source

Thrown at src/TokenParser/UseTokenParser.php:43

 *
 *    {% use "blocks.html" %}
 *
 *    {% block title %}{% endblock %}
 *    {% block content %}{% endblock %}
 *
 * @see https://twig.symfony.com/doc/templates.html#horizontal-reuse for details.
 *
 * @internal
 */
final class UseTokenParser extends AbstractTokenParser
{
    public function parse(Token $token): Node
    {
        $template = $this->parser->parseExpression();
        $stream = $this->parser->getStream();

        if (!$template instanceof ConstantExpression) {
            throw new SyntaxError('The template references in a "use" statement must be a string.', $stream->getCurrent()->getLine(), $stream->getSourceContext());
        }

        $targets = [];
        if ($stream->nextIf('with')) {
            while (true) {
                $name = $stream->expect(Token::NAME_TYPE)->getValue();

                $alias = $name;
                if ($stream->nextIf('as')) {
                    $alias = $stream->expect(Token::NAME_TYPE)->getValue();
                }

                $targets[$name] = new ConstantExpression($alias, -1);

                if (!$stream->nextIf(Token::PUNCTUATION_TYPE, ',')) {
                    break;
                }
            }

View on GitHub (pinned to a414c3a491)