twigphp/Twig · error · RuntimeError

Block " " is not defined in trait " ".

Error message

Block "%s" is not defined in trait "%s".

What it means

When compiling a template that uses another template as a trait, Twig emits runtime checks that each requested block exists in the trait's block table ($_trait_N_blocks). A referenced block key missing from the trait template raises this RuntimeError at runtime.

Solutions

1. Define the missing block in the trait template
2. Fix the block key/alias in the {% use %} statement to match an existing block
3. Verify you are loading the intended trait template version

Example fix

// before
{% use 'blocks.html' with { content: 'body' } %} {# blocks.html has no 'body' block #}
// after
{% use 'blocks.html' with { content: 'content' } %}

// Verify every used block exists in the trait template
preg_match_all('/{%\\s*block\\s+(\\w+)/', file_get_contents($traitPath), $m);
$defined = $m[1];
$needed = ['content', 'footer'];
$missing = array_diff($needed, $defined);
if ($missing) throw new RuntimeException('Missing blocks: '.implode(',', $missing));

try {
    $twig->render($template, $context);
} catch (\Twig\Error\RuntimeError $e) {
    if (str_contains($e->getMessage(), 'is not defined in trait')) {
        // fix block name or define it in the trait
    }
    throw $e;
}

When it happens

Trigger: {% use 'trait.html' with { footer: 'pageFooter' } %} (or implicit same-name use) where trait.html does not define the requested block.

Common situations: Renaming a block in the trait template without updating the using template; alias targets misspelled; using a trait file from an older version.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Template " " cannot be used as a trait.
• A "block" tag cannot be under a
• Calling the "parent" function outside of a block is…
• Calling the "parent" function on a template that does not…
• A template that extends another one cannot include content…

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

Appendix: source

Thrown at src/Node/ModuleNode.php:252

                    ->write(\sprintf("if (!\$_trait_%s->unwrap()->isTraitable()) {\n", $i))
                    ->indent()
                    ->write("throw new RuntimeError('Template \"'.")
                    ->subcompile($trait->getNode('template'))
                    ->raw(".'\" cannot be used as a trait.', ")
                    ->repr($node->getTemplateLine())
                    ->raw(", \$this->source);\n")
                    ->outdent()
                    ->write("}\n")
                    ->write(\sprintf("\$_trait_%s_blocks = \$_trait_%s->unwrap()->getBlocks();\n\n", $i, $i))
                ;

                foreach ($trait->getNode('targets') as $key => $value) {
                    $compiler
                        ->write(\sprintf('if (!isset($_trait_%s_blocks[', $i))
                        ->string($key)
                        ->raw("])) {\n")
                        ->indent()
                        ->write("throw new RuntimeError(sprintf('Block \"%s\" is not defined in trait \"%s\".', ")
                        ->string($key)
                        ->raw(', ')
                        ->subcompile($trait->getNode('template'))
                        ->raw('), ')
                        ->repr($node->getTemplateLine())
                        ->raw(", \$this->source);\n")
                        ->outdent()
                        ->write("}\n\n")

                        ->write(\sprintf('$_trait_%s_blocks[', $i))
                        ->subcompile($value)
                        ->raw(\sprintf('] = $_trait_%s_blocks[', $i))
                        ->string($key)
                        ->raw(\sprintf(']; unset($_trait_%s_blocks[', $i))
                        ->string($key)
                        ->raw(']); $this->traitAliases[')
                        ->subcompile($value)
                        ->raw('] = ')

View on GitHub (pinned to a414c3a491)