quarkusio/quarkus · error · java.lang.IllegalStateException

Templates that are not backed by a file must provide extensi

Error message

Templates that are not backed by a file must provide extension info

What it means

TemplatePathBuildItem.Builder.build() validates that a template entry is either backed by a real file (fullPath set) or carries extension info identifying which extension provides it. Content-based templates without a file path must declare extensionInfo so the template can be attributed and resolved; otherwise IllegalStateException is thrown at build time.

Source

Thrown at extensions/qute/deployment/src/main/java/io/quarkus/qute/deployment/TemplatePathBuildItem.java:270

        public Builder priority(int priority) {
            this.priority = priority;
            return this;
        }

        /**
         * Set the parser config for the template.
         *
         * @param parserConfig
         * @return self
         */
        public Builder parserConfig(ParserConfig parserConfig) {
            this.parserConfig = parserConfig;
            return this;
        }

        public TemplatePathBuildItem build() {
            if (fullPath == null && extensionInfo == null) {
                throw new IllegalStateException("Templates that are not backed by a file must provide extension info");
            }
            return new TemplatePathBuildItem(path, content, fullPath, extensionInfo, priority, source, parserConfig);
        }

    }

}

View on GitHub (pinned to e1c734241f)

Solutions

Call .extensionInfo("your-extension") on the TemplatePathBuildItem.Builder before build()
Or provide a real file-backed path via .fullPath(...) instead of inline content
Check which custom build step produces the item and add the missing builder call

Example fix

// before
TemplatePathBuildItem.builder().content("...content...").build();
// after
TemplatePathBuildItem.builder().content("...content...").extensionInfo("my-extension").build();

Defensive patterns

Strategy: validation

Validate before calling

TemplatePathBuildItem.Builder b = TemplatePathBuildItem.builder().content(templateContent);
if (fullPath == null && extensionInfo == null) {
    b.extensionInfo("my-extension");
}
TemplatePathBuildItem item = b.build();

Prevention

Always set extensionInfo when building content-based (non-file) templates
Add a unit test invoking your build step that catches IllegalStateException from build()
Review builder calls for completeness whenever TemplatePathBuildItem's builder API changes

When it happens

Trigger: A custom build step creates a TemplatePathBuildItem with TemplatePathBuildItem.builder().content(...) but never calls extensionInfo(...) on the builder, then invokes build().

Common situations: Extension authors synthesizing templates from annotation data or generated content and forgetting the extensionInfo builder method; upgrading Qute where the builder gained this stricter check.

Related errors

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/d5158e9fa33d1bdc. Report an issue: GitHub.