quarkusio/quarkus · error · java.io.UncheckedIOException

Unable to read the template content from path: <path>

Error message

Unable to read the template content from path: <path>

What it means

Wrapped as UncheckedIOException when Qute cannot read the template file at the given path via Files.readString. The path exists logically in the build (e.g. referenced by @TemplateContents from path or a template file discovered during the build) but cannot be opened/read with the configured charset, typically because it does not exist on disk or an I/O error occurs.

Source

Thrown at extensions/qute/deployment/src/main/java/io/quarkus/qute/deployment/QuteProcessor.java:3867

        return templatePaths;
    }

    private IllegalStateException newDuplicateError(Map<String, List<TemplatePathBuildItem>> groupedByPath) {
        StringBuilder builder = new StringBuilder("Duplicate templates found:");
        for (Entry<String, List<TemplatePathBuildItem>> e : groupedByPath.entrySet()) {
            builder.append("\n\t- ")
                    .append(e.getKey())
                    .append(": ")
                    .append(e.getValue().stream().map(TemplatePathBuildItem::getSourceInfo).collect(Collectors.toList()));
        }
        return new IllegalStateException(builder.toString());
    }

    static String readTemplateContent(Path path, Charset defaultCharset) {
        try {
            return Files.readString(path, defaultCharset);
        } catch (IOException e) {
            throw new UncheckedIOException("Unable to read the template content from path: " + path, e);
        }
    }

    /**
     * Java members lookup config.
     *
     * @see QuteProcessor#findProperty(String, ClassInfo, JavaMemberLookupConfig)
     * @see QuteProcessor#findMethod(VirtualMethodPart, ClassInfo, Expression, IndexView, Function, Map, JavaMemberLookupConfig)
     */
    interface JavaMemberLookupConfig {

        IndexView index();

        Predicate<AnnotationTarget> filter();

        boolean declaredMembersOnly();

        default void nextPart() {

View on GitHub (pinned to e1c734241f)

Solutions

1. Verify the file exists at the exact path (case-sensitive) under src/main/resources and fix the path/reference
2. Check file permissions and that the file is included by the build (not excluded by resource filters or .gitignore)
3. Rebuild/clean the project if the resources were not copied to target/classes
4. Ensure the configured charset (quarkus.qute.default-charset) matches the file encoding

Example fix

// before
@Location("emails/welcom.html") // typo: file is welcome.html
Template welcome;

// after
@Location("emails/welcome.html")
Template welcome;

// Verify the template path exists before referencing it
Path p = Path.of("src/main/resources", "templates/emails/welcome.html");
if (!Files.isRegularFile(p)) {
    throw new IllegalStateException("Template missing: " + p);
}

try {
    String content = Files.readString(path, charset);
} catch (IOException e) {
    throw new UncheckedIOException("Unable to read template at " + path, e);
}

When it happens

Trigger: A template path referenced from an annotation or config does not exist under src/main/resources; wrong defaultCharset causing read failure is unlikely — the usual cause is IOException: missing file, unreadable file permissions, or a path with wrong casing on case-sensitive filesystems.

Common situations: Typo in the template path or extension (.html vs .txt); file deleted or renamed while still referenced; CI checkout case sensitivity differences (Windows-authored path casing); resource filtering/exclusion removing templates from the build.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• No template matching the path <templatePath> could be found
• Failed to open path tree with root %s
• Failed to read %s
• Failed to read resources from classpath
• Failed to create output directory for generated sources: %s

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