How Drupal Finds Twig Templates
Theme registry, template suggestions, loader paths, and cache rebuilds explained through a practical template-not-found failure.
When Twig says a Drupal template is not defined, the file can exist and still be undiscoverable. Drupal resolves templates through extension discovery, the theme registry, naming conventions, active-theme inheritance, and configured Twig loaders before PHP ever renders the markup.
Start with the active theme
Confirm which theme handles the request and whether it declares a base theme. A template placed under an inactive theme, the wrong subdirectory, or an unexpected base-theme relationship will not satisfy the registry entry. Keep templates under the conventional templates directory and group them by purpose without changing their Drupal suggestion names.
Understand registry names and loader roots
Drupal’s registry stores a template path relative to the Drupal web root, such as themes/custom/example/templates/layout/html.html.twig. Twig loaders must resolve that registry name from the same application root. A mismatch between the runtime root and the registered path produces a loader exception even though a filesystem check elsewhere finds the file.
Rebuild the right caches
Template discovery and suggestions are cached. Rebuild Drupal caches after adding, moving, or renaming Twig files or changing theme metadata. If the error persists, inspect the active theme, registry suggestion, and loader path instead of repeatedly clearing caches; cache rebuilds reveal changes but cannot correct an invalid path.
Working example
{# themes/custom/example/templates/layout/page.html.twig #}
<main id="main-content">
{{ page.content }}
</main>Key Takeaways
- A present file is not necessarily a registered template.
- Resolve registry paths from Drupal’s web root.
- Rebuild caches after discovery changes, then inspect paths if the error remains.