quarkusio/quarkus · error · IllegalArgumentException

Unsupported format: ${format}

Error message

Unsupported format: ${format}

What it means

Formatter.getFormatter maps the configured Format enum to a formatter implementation and throws IllegalArgumentException for any value other than asciidoc or markdown. The plugin only ships those two formatters.

Source

Thrown at devtools/config-doc-maven-plugin/src/main/java/io/quarkus/maven/config/doc/generator/Formatter.java:44

    int adjustedLevel(ConfigSection configSection, boolean multiRoot);

    String escapeCellContent(String value);

    String toAnchor(String value);

    String formatSectionTitle(ConfigSection configSection);

    String formatName(Extension extension);

    static Formatter getFormatter(GenerationReport generationReport, JavadocRepository javadocRepository,
            boolean enableEnumTooltips, Format format) {
        switch (format) {
            case asciidoc:
                return new AsciidocFormatter(generationReport, javadocRepository, enableEnumTooltips);
            case markdown:
                return new MarkdownFormatter(generationReport, javadocRepository);
            default:
                throw new IllegalArgumentException("Unsupported format: " + format);
        }
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

1. Set format=asciidoc or format=markdown explicitly
2. Check supported values of the Format enum in your plugin version (mvn help:describe or the plugin docs)
3. Upgrade or downgrade the plugin to a version supporting the desired format

Example fix

// before
mvn ... -Dformat=html
// after
mvn ... -Dformat=markdown

Set<String> supported = Set.of("asciidoc", "markdown");
if (!supported.contains(configuredFormat)) {
    throw new IllegalArgumentException(
        "format must be one of " + supported + ", got: " + configuredFormat);
}

try {
    mojo.execute();
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Unsupported format")) {
        logger.error("Use asciidoc or markdown: " + e.getMessage());
    }
}

When it happens

Trigger: generate-config-doc runs with -Dformat set to a value that resolves to a Format enum constant with no case branch (custom/typo/unsupported format from a different plugin version).

Common situations: Typo in the format parameter; copying a config example from another docs tool; plugin version where a format was added/removed relative to the docs you followed.

Related errors

• Either the `extension` or `extensions` parameter must be set
• Cannot specify both class and method name
• The project artifact's extension is '${extension}' while thi
• Specifying a stream requires the Quarkus extension registry
• Unrecognized dependency flag '<trimmed>'. Supported flags: O

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