How Drupal Finds Twig Templates
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>Template suggestions start with a theme hook
Drupal does not begin by scanning every Twig file on disk. A render array references a theme hook, the theme registry describes that hook, and suggestion logic can narrow the template according to bundle, view mode, field name, route context, or other supported patterns. The active theme then resolves the best available implementation.
Understanding that chain explains why inventing a plausible Twig filename is not always enough. The filename must correspond to a suggestion Drupal actually produced.
Namespaces solve a different template problem
Twig namespaces such as a custom theme namespace are useful when one template explicitly includes another template by path. That is different from Drupal's automatic theme-hook resolution. Confusing the two mechanisms can lead to a file that is includeable manually but is never selected as the implementation of a Drupal theme hook.
Preprocess and template selection are separate
Preprocess functions prepare variables for a theme hook; template suggestion logic determines which template implementation Drupal will use. Keeping those responsibilities separate makes debugging easier. If the wrong file is selected, inspect suggestions. If the correct file is selected but data is missing, inspect preprocess and the render array.
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.