OpenAPITools/openapi-generator · error · IllegalArgumentException

The [%s] documentation provider does not support [%s] as com

Error message

The [%s] documentation provider does not support [%s] as complementary annotation library

What it means

AbstractJavaCodegen.processOpts throws IllegalArgumentException when the documentation provider is valid for the generator but does not pair with the chosen annotation library. Each DocumentationProvider declares its compatible libraries (per DocumentationProviderFeatures): source supports all, swagger1 only swagger1, swagger2 only swagger2, springdoc only swagger2.

Source

Thrown at modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/AbstractJavaCodegen.java:442

                throw new IllegalArgumentException(msg);
            }

            annotationLibrary = AnnotationLibrary.ofCliOption(
                    (String) additionalProperties.getOrDefault(ANNOTATION_LIBRARY,
                            documentationProvider.getPreferredAnnotationLibrary().toCliOptValue())
            );

            if (!supportedAnnotationLibraries().contains(annotationLibrary)) {
                String msg = String.format(Locale.ROOT, "The Annotation Library [%s] is not supported by this generator",
                        annotationLibrary.toCliOptValue());
                throw new IllegalArgumentException(msg);
            }

            if (!documentationProvider.supportedAnnotationLibraries().contains(annotationLibrary)) {
                String msg = String.format(Locale.ROOT,
                        "The [%s] documentation provider does not support [%s] as complementary annotation library",
                        documentationProvider.toCliOptValue(), annotationLibrary.toCliOptValue());
                throw new IllegalArgumentException(msg);
            }

            additionalProperties.put(DOCUMENTATION_PROVIDER, documentationProvider.toCliOptValue());
            additionalProperties.put(documentationProvider.getPropertyName(), true);
            additionalProperties.put(ANNOTATION_LIBRARY, annotationLibrary.toCliOptValue());
            additionalProperties.put(annotationLibrary.getPropertyName(), true);
        } else {
            additionalProperties.put(DOCUMENTATION_PROVIDER, DocumentationProvider.NONE);
            additionalProperties.put(ANNOTATION_LIBRARY, AnnotationLibrary.NONE);
        }

        convertPropertyToBooleanAndWriteBack(GENERATE_CONSTRUCTOR_WITH_ALL_ARGS, this::setGenerateConstructorWithAllArgs);
        convertPropertyToBooleanAndWriteBack(GENERATE_BUILDERS, this::setGenerateBuilders);
        convertPropertyToBooleanAndWriteBack(DISABLE_DISCRIMINATOR_JSON_IGNORE_PROPERTIES, this::setDisableDiscriminatorJsonIgnoreProperties);
        if (StringUtils.isEmpty(System.getenv("JAVA_POST_PROCESS_FILE"))) {
            LOGGER.info("Environment variable JAVA_POST_PROCESS_FILE not defined so the Java code may not be properly formatted. To define it, try 'export JAVA_POST_PROCESS_FILE=\"/usr/local/bin/clang-format -i\"' (Linux/Mac)");
            LOGGER.info("NOTE: To enable file post-processing, 'enablePostProcessFile' must be set to `true` (--enable-post-process-file for CLI).");
        } else if (!this.isEnablePostProcessFile()) {

View on GitHub (pinned to fcec517be3)

Solutions

Align the pair with the provider matrix: swagger1→swagger1, swagger2→swagger2, springdoc→swagger2, source→any supported by the generator.
Set only documentationProvider and omit annotationLibrary so the provider's preferred library is chosen automatically.
Migrate both options together when moving between swagger versions.

Example fix

# before:
openapi-generator-cli generate -g java -i api.yaml -p documentationProvider=swagger2 -p annotationLibrary=microprofile
# after:
openapi-generator-cli generate -g java -i api.yaml -p documentationProvider=swagger2 -p annotationLibrary=swagger2
# or let the provider pick: -p documentationProvider=swagger2 (omit annotationLibrary)

Defensive patterns

Strategy: validation

Validate before calling

// Validate the provider/library pairing before invoking the generator
Map<String, Set<String>> compatible = Map.of(
    "none", Set.of("none"),
    "source", Set.of("none", "swagger1", "swagger2", "microprofile"),
    "swagger1", Set.of("swagger1"),
    "swagger2", Set.of("swagger2"),
    "springdoc", Set.of("swagger2"));
if (!compatible.getOrDefault(provider, Set.of()).contains(annotationLibrary))
    throw new IllegalArgumentException(provider + " does not pair with " + annotationLibrary);

Type guard

type Provider = 'none' | 'source' | 'swagger1' | 'swagger2' | 'springdoc';
type Library = 'none' | 'swagger1' | 'swagger2' | 'microprofile';
const COMBINATIONS: Record<Provider, Library[]> = {
    none: ['none'],
    source: ['none', 'swagger1', 'swagger2', 'microprofile'],
    swagger1: ['swagger1'],
    swagger2: ['swagger2'],
    springdoc: ['swagger2'],
};
export function isValidCombination(p: string, l: string): boolean {
    return p in COMBINATIONS && (COMBINATIONS as Record<string, Library[]>)[p].includes(l as Library);
}

Prevention

Set documentationProvider only, and let annotationLibrary default to the provider's preferred choice.
When migrating swagger1→swagger2 or springdoc, change both options together.
Encode the pairing matrix in your codegen config validation so invalid pairs never reach the CLI.

When it happens

Trigger: Combinations like -p documentationProvider=swagger2 -p annotationLibrary=microprofile, or documentationProvider=source with annotationLibrary=swagger1 on a generator that only supports swagger2 — the documentationProvider.supportedAnnotationLibraries() membership check fails after both options are resolved.

Common situations: Assembling option sets piecemeal from different examples; upgrading a generator whose default provider changed (e.g. to source) while the config pins an old annotation library; migrating from swagger1 to swagger2 annotations but only changing one of the two options.

Related errors

AI-assisted analysis of OpenAPITools/openapi-generator@fcec517be3 (2026-08-22). Data as JSON: /api/errors/ba5971f0089d5f97. Report an issue: GitHub.