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

Pick a supported value: `annotationLibrary=swagger2` (the springdoc default), `swagger1`, or `none`.

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

kotlin-spring accepts only 'none', 'swagger1' and 'swagger2' as annotation libraries (supportedAnnotationLibraries() at KotlinSpringServerCodegen.java:442). In processOpts() the CLI value is parsed via AnnotationLibrary.ofCliOption() and, if it is a valid enum constant this generator does not offer (e.g. 'javadoc'), an IllegalArgumentException is thrown. Values are upper-cased before matching, so case is not the issue — the value itself must be one of the three.

Source

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

                            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);
        }
        if (additionalProperties.containsKey(USE_SPRING_BOOT3)) {

View on GitHub (pinned to fcec517be3)

Solutions

Pick a supported value: `annotationLibrary=swagger2` (the springdoc default), `swagger1`, or `none`.
If you need javadoc-style output, use a generator whose supportedAnnotationLibraries() includes javadoc (check with `config-help -g <lang>`).
Run `openapi-generator-cli config-help -g kotlin-spring` and copy the enumerated values verbatim.

Example fix

# before
openapi-generator-cli generate -g kotlin-spring -i api.yaml \
  --additional-properties annotationLibrary=javadoc
# after
openapi-generator-cli generate -g kotlin-spring -i api.yaml \
  --additional-properties annotationLibrary=swagger2

Defensive patterns

Strategy: validation

Validate before calling

// allow-list mirrors supportedAnnotationLibraries() for kotlin-spring
Set<String> supported = Set.of("NONE", "SWAGGER1", "SWAGGER2");
String al = String.valueOf(opts.getOrDefault("annotationLibrary", "SWAGGER2"))
        .toUpperCase(Locale.ROOT);
if (!supported.contains(al)) {
    throw new IllegalArgumentException(
        "kotlin-spring annotationLibrary must be one of " + supported);
}

Try / catch

try {
    new DefaultGenerator().opts(clientOptInput).generate();
} catch (IllegalArgumentException e) {
    // message names the rejected annotation library
    throw new BuildException("Invalid kotlin-spring options: " + e.getMessage(), e);
}

Prevention

Check config-help output per generator before adding annotationLibrary to options.
Prefer omitting annotationLibrary so it defaults to the provider's preferred library.
Centralize generator options in one module and review them on generator upgrades.

When it happens

Trigger: Running `-g kotlin-spring` with `--additional-properties annotationLibrary=javadoc` (javadoc is a valid AnnotationLibrary used by other generators but not listed for kotlin-spring). Unrecognized strings fail earlier in valueOf() with a 'No enum constant' message instead of this one.

Common situations: Reusing java-spring or another generator's configOptions (where javadoc is supported) in a kotlin-spring Maven/Gradle plugin block; disabling annotation processing and guessing the option name for plain Javadoc output.

Related errors

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