quarkusio/quarkus · error · IllegalArgumentException

Unable to find a template for these candidates ${candidates}

Error message

Unable to find a template for these candidates ${candidates}

What it means

getTemplate loads the Qute templates used by the doc generator from the classpath and throws IllegalArgumentException when none of the candidate template resource names could be opened. This means the plugin's bundled template resources are missing from the classpath.

Source

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

        candidates.add(
                root + "/" + format + "/" + theme + "/" + (tag ? "tags/" : "") + template + ".qute." + format.getExtension());
        if (!Format.DEFAULT_THEME.equals(theme)) {
            candidates
                    .add(root + "/" + format + "/" + Format.DEFAULT_THEME + "/" + (tag ? "tags/" : "") + template + ".qute."
                            + format.getExtension());
        }

        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<>();

View on GitHub (pinned to e1c734241f)

Solutions

1. Rebuild/reinstall the plugin or update it to a consistent released version
2. Check the configured format/theme maps to an existing bundled template
3. Inspect the plugin jar for the template resources (unzip -l) to confirm presence

Example fix

// before
mvn io.quarkus:quarkus-config-doc-maven-plugin:... -Dformat=custom
// after
mvn io.quarkus:quarkus:config-doc-maven-plugin:... -Dformat=asciidoc

// Verify the plugin jar carries its templates
Process p = new ProcessBuilder("unzip", "-l",
    pluginJarPath, "|", "grep", "templates").start();

try {
    mojo.execute();
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Unable to find a template")) {
        logger.error("Reinstall plugin: " + e.getMessage());
    }
}

When it happens

Trigger: initializeQuteEngine resolves a template locator that calls getTemplate; every candidate InputStream is null, i.e. no candidate resource exists for the configured format/theme.

Common situations: A mismatched or corrupted quarkus-config-doc-maven-plugin jar missing its template resources; using a custom format/theme value that has no matching template; version skew between the plugin and its templates.

Related errors

• Unable to read the template: ${template}
• Failed to resolve maven plugin version containing <cls>
• Failed to locate io.quarkus:quarkus-core-deployment on the a
• Failed to locate <pomPropsPath> on the classpath
• Failed to load <pomPropsPath> from the classpath

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