twigphp/Twig · error · Twig\Error\SyntaxError

Unknown " " configuration.

Error message

Unknown "%s" configuration.

What it means

This Twig SyntaxError is thrown by CacheTokenParser::parse while parsing a {% cache %} tag. The tag only accepts two named modifiers, 'ttl' and 'tags'; any other name token inside the tag is rejected at compile time with the offending key name in the message. It is a template compile-time guard against misspelled or unsupported cache options.

Solutions

1. Replace the unknown modifier with one of the supported ones: 'ttl' or 'tags'.
2. Check the exact spelling of the modifier name inside the {% cache %} tag.
3. Consult the cache-extra documentation for the supported tag syntax.
4. If you need extra behavior (e.g. cache keys), use an expression inside ttl/tags arguments or wrap the block differently.

Example fix

// before
{% cache lifetime=60 %}...{% endcache %}
// after
{% cache ttl=60 %}...{% endcache %}

$allowed = ['ttl', 'tags'];
if (!in_array($modifier, $allowed, true)) {
    throw new InvalidArgumentException(sprintf('Modifier must be one of: %s, got "%s"', implode(', ', $allowed), $modifier));
}

try {
    $twig->render($template);
} catch (\Twig\Error\SyntaxError $e) {
    if (str_contains($e->getMessage(), 'Unknown')) {
        // log template name + line, surface fix to developer
    }
    throw $e;
}

When it happens

Trigger: Writing a {% cache %} tag with a modifier name other than 'ttl' or 'tags', e.g. {% cache lifetime=60 %} or {% cache key="foo" %} or a typo like {% cache ttll=60 %}.

Common situations: Developers migrating from other caching bundles expecting a 'key' or 'lifetime' option, or simply typo-ing 'ttl'/'tags' inside the cache tag.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• The " " modifier takes exactly one argument (0 given).
• The " " modifier takes exactly one argument (2 given).
• Calling the "parent" function outside of a block is…
• Calling the "parent" function on a template that does not…
• The first argument of the "enum_cases" function must be a…

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

Appendix: source

Thrown at extra/cache-extra/TokenParser/CacheTokenParser.php:34

use Twig\Node\Expression\Filter\RawFilter;
use Twig\Node\Node;
use Twig\Node\PrintNode;
use Twig\Token;
use Twig\TokenParser\AbstractTokenParser;

class CacheTokenParser extends AbstractTokenParser
{
    public function parse(Token $token): Node
    {
        $stream = $this->parser->getStream();
        $key = $this->parser->parseExpression();

        $ttl = null;
        $tags = null;
        while ($stream->test(Token::NAME_TYPE)) {
            $k = $stream->getCurrent()->getValue();
            if (!\in_array($k, ['ttl', 'tags'], true)) {
                throw new SyntaxError(\sprintf('Unknown "%s" configuration.', $k), $stream->getCurrent()->getLine(), $stream->getSourceContext());
            }

            $stream->next();
            $stream->expect(Token::OPERATOR_TYPE, '(');
            $line = $stream->getCurrent()->getLine();
            if ($stream->test(Token::PUNCTUATION_TYPE, ')')) {
                throw new SyntaxError(\sprintf('The "%s" modifier takes exactly one argument (0 given).', $k), $line, $stream->getSourceContext());
            }
            $arg = $this->parser->parseExpression();
            if ($stream->test(Token::PUNCTUATION_TYPE, ',')) {
                throw new SyntaxError(\sprintf('The "%s" modifier takes exactly one argument (2 given).', $k), $line, $stream->getSourceContext());
            }
            $stream->expect(Token::PUNCTUATION_TYPE, ')');

            if ('ttl' === $k) {
                $ttl = $arg;
            } elseif ('tags' === $k) {
                $tags = $arg;

View on GitHub (pinned to a414c3a491)