quarkusio/quarkus · error · UncheckedIOException

Unable to read the template: ${template}

Error message

Unable to read the template: ${template}

What it means

After locating the template resource, getTemplate reads its bytes as UTF-8; an IOException during reading is wrapped in UncheckedIOException 'Unable to read the template: <template>'. The resource exists but its content could not be read.

Source

Thrown at devtools/config-doc-maven-plugin/src/main/java/io/quarkus/maven/config/doc/GenerateConfigDocMojo.java:493

        }

        InputStream is = null;
        ;
        for (String candidate : candidates) {
            is = Thread.currentThread().getContextClassLoader().getResourceAsStream(candidate);
            if (is != null) {
                break;
            }
        }

        if (is == null) {
            throw new IllegalArgumentException("Unable to find a template for these candidates " + candidates);
        }

        try {
            return new String(is.readAllBytes(), StandardCharsets.UTF_8);
        } catch (IOException e) {
            throw new UncheckedIOException("Unable to read the template: " + template, e);
        } finally {
            try {
                is.close();
            } catch (IOException e) {
                throw new UncheckedIOException("Unable to close InputStream for template: " + template, e);
            }
        }
    }

    private static Set<String> collectDuplicatePropertyPaths(MergedModel mergedModel) {
        Set<String> seenBuildTime = new HashSet<>();
        Set<String> seenRunTime = new HashSet<>();

        for (Map<ConfigRootKey, ConfigRoot> configRoots : mergedModel.getConfigRoots().values()) {
            for (ConfigRoot configRoot : configRoots.values()) {
                collectPropertyPhases(configRoot, seenBuildTime, seenRunTime);
            }
        }

View on GitHub (pinned to e1c734241f)

Solutions

1. Delete the plugin artifact from the local Maven repository and re-download (mvn -U)
2. Reinstall the plugin locally with mvn install if built from source
3. Verify the jar integrity and rebuild if it is a local uber-jar

Example fix

// before
~/.m2/repository/io/quarkus/quarkus-config-doc-maven-plugin/  <!-- corrupted -->
// after
rm -rf ~/.m2/repository/io/quarkus/quarkus-config-doc-maven-plugin/ && mvn -U ...

// Check jar integrity before build
Files.size(Paths.get(pluginJarPath)); // and compare checksum if published

try {
    mojo.execute();
} catch (UncheckedIOException e) {
    if (e.getMessage().startsWith("Unable to read the template")) {
        // purge artifact from ~/.m2 and retry with -U
    }
}

When it happens

Trigger: The InputStream for the resolved template fails mid-read: the jar/resource is corrupted, truncated on disk, or the underlying stream errors.

Common situations: Corrupted local Maven repository cache (~/.m2) after an interrupted download; damaged plugin jar in a shaded/uber jar build.

Related errors

• Unable to render all config
• Unable to create directory: ${directory}
• Unable to collect the target directories
• Unable to find a template for these candidates ${candidates}
• Unable to close InputStream for template: ${template}

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