What causes "The Annotation Library [%s] is not supported by this generator" in OpenAPITools/openapi-generator?

Choose an annotation library the specific generator supports (see the generator's docs/help).

OpenAPITools/openapi-generator · error · IllegalArgumentException

The Annotation Library [%s] is not supported by this generat

Error message

The Annotation Library [%s] is not supported by this generator

What it means

AbstractJavaCodegen.processOpts throws IllegalArgumentException when the annotationLibrary option is a valid value (none, swagger1, swagger2, microprofile) but the concrete generator does not include it in supportedAnnotationLibraries(). The check runs after the documentation provider is resolved, since the provider picks a preferred default library.

Source

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

                            defaultDocumentationProvider().toCliOptValue())
            );

            if (!supportedDocumentationProvider().contains(documentationProvider)) {
                String msg = String.format(Locale.ROOT,
                        "The [%s] Documentation Provider is not supported by this generator",
                        documentationProvider.toCliOptValue());
                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);
        }

View on GitHub (pinned to fcec517be3)

Solutions

Choose an annotation library the specific generator supports (see the generator's docs/help).
Drop the annotationLibrary option and let the documentation provider's preferred library apply.
If the library is a hard requirement, pick a generator that supports it.

Example fix

# before (generator supports only swagger2):
openapi-generator-cli generate -g java -i api.yaml -p annotationLibrary=microprofile
# after:
openapi-generator-cli generate -g java -i api.yaml -p annotationLibrary=swagger2

Defensive patterns

Strategy: validation

Validate before calling

// Programmatic use: verify against the generator instance before setting options
String lib = (String) additionalProperties.getOrDefault("annotationLibrary",
        provider.getPreferredAnnotationLibrary().toCliOptValue());
AnnotationLibrary parsedLib = AnnotationLibrary.ofCliOption(lib.toUpperCase(Locale.ROOT));
if (!gen.supportedAnnotationLibraries().contains(parsedLib))
    throw new IllegalArgumentException("Pick from: " + gen.supportedAnnotationLibraries());

Type guard

const ANNOTATION_LIBRARIES = ['none', 'swagger1', 'swagger2', 'microprofile'] as const;
export type AnnotationLibrary = typeof ANNOTATION_LIBRARIES[number];
export function isAnnotationLibrary(v: string): v is AnnotationLibrary {
    return (ANNOTATION_LIBRARIES as readonly string[]).includes(v);
}
// NOTE: still verify the concrete generator's supportedAnnotationLibraries() set.

Prevention

Treat annotationLibrary as generator-specific; do not copy it between generators blindly.
Prefer omitting annotationLibrary so the provider's preferred library is used.
When a generator changes its default provider across versions, re-check pinned library options.

When it happens

Trigger: Passing -p annotationLibrary=microprofile to a Java generator whose supportedAnnotationLibraries() excludes it; note the resolved default comes from documentationProvider.getPreferredAnnotationLibrary() when the option is absent, so a generator/provider pairing can also drag in an unsupported default.

Common situations: Reusing option blocks between Java generators that support different annotation libraries; requesting swagger1 annotations on a generator that only supports swagger2; version upgrades that narrowed the supported set.

Related errors

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