{"record":{"id":"ba5971f0089d5f97","repo":"OpenAPITools/openapi-generator","slug":"the-s-documentation-provider-does-not-support","errorCode":null,"errorMessage":"The [%s] documentation provider does not support [%s] as complementary annotation library","messagePattern":"The \\[(.+?)\\] documentation provider does not support \\[(.+?)\\] as complementary annotation library","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/AbstractJavaCodegen.java","lineNumber":442,"sourceCode":"                throw new IllegalArgumentException(msg);\n            }\n\n            annotationLibrary = AnnotationLibrary.ofCliOption(\n                    (String) additionalProperties.getOrDefault(ANNOTATION_LIBRARY,\n                            documentationProvider.getPreferredAnnotationLibrary().toCliOptValue())\n            );\n\n            if (!supportedAnnotationLibraries().contains(annotationLibrary)) {\n                String msg = String.format(Locale.ROOT, \"The Annotation Library [%s] is not supported by this generator\",\n                        annotationLibrary.toCliOptValue());\n                throw new IllegalArgumentException(msg);\n            }\n\n            if (!documentationProvider.supportedAnnotationLibraries().contains(annotationLibrary)) {\n                String msg = String.format(Locale.ROOT,\n                        \"The [%s] documentation provider does not support [%s] as complementary annotation library\",\n                        documentationProvider.toCliOptValue(), annotationLibrary.toCliOptValue());\n                throw new IllegalArgumentException(msg);\n            }\n\n            additionalProperties.put(DOCUMENTATION_PROVIDER, documentationProvider.toCliOptValue());\n            additionalProperties.put(documentationProvider.getPropertyName(), true);\n            additionalProperties.put(ANNOTATION_LIBRARY, annotationLibrary.toCliOptValue());\n            additionalProperties.put(annotationLibrary.getPropertyName(), true);\n        } else {\n            additionalProperties.put(DOCUMENTATION_PROVIDER, DocumentationProvider.NONE);\n            additionalProperties.put(ANNOTATION_LIBRARY, AnnotationLibrary.NONE);\n        }\n\n        convertPropertyToBooleanAndWriteBack(GENERATE_CONSTRUCTOR_WITH_ALL_ARGS, this::setGenerateConstructorWithAllArgs);\n        convertPropertyToBooleanAndWriteBack(GENERATE_BUILDERS, this::setGenerateBuilders);\n        convertPropertyToBooleanAndWriteBack(DISABLE_DISCRIMINATOR_JSON_IGNORE_PROPERTIES, this::setDisableDiscriminatorJsonIgnoreProperties);\n        if (StringUtils.isEmpty(System.getenv(\"JAVA_POST_PROCESS_FILE\"))) {\n            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)\");\n            LOGGER.info(\"NOTE: To enable file post-processing, 'enablePostProcessFile' must be set to `true` (--enable-post-process-file for CLI).\");\n        } else if (!this.isEnablePostProcessFile()) {","sourceCodeStart":424,"sourceCodeEnd":460,"githubUrl":"https://github.com/OpenAPITools/openapi-generator/blob/fcec517be3cf5b7964296bcba25fbc97541484e7/modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/AbstractJavaCodegen.java#L424-L460","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before:\nopenapi-generator-cli generate -g java -i api.yaml -p documentationProvider=swagger2 -p annotationLibrary=microprofile\n# after:\nopenapi-generator-cli generate -g java -i api.yaml -p documentationProvider=swagger2 -p annotationLibrary=swagger2\n# or let the provider pick: -p documentationProvider=swagger2 (omit annotationLibrary)","handlingStrategy":"validation","validationCode":"// Validate the provider/library pairing before invoking the generator\nMap<String, Set<String>> compatible = Map.of(\n    \"none\", Set.of(\"none\"),\n    \"source\", Set.of(\"none\", \"swagger1\", \"swagger2\", \"microprofile\"),\n    \"swagger1\", Set.of(\"swagger1\"),\n    \"swagger2\", Set.of(\"swagger2\"),\n    \"springdoc\", Set.of(\"swagger2\"));\nif (!compatible.getOrDefault(provider, Set.of()).contains(annotationLibrary))\n    throw new IllegalArgumentException(provider + \" does not pair with \" + annotationLibrary);","typeGuard":"type Provider = 'none' | 'source' | 'swagger1' | 'swagger2' | 'springdoc';\ntype Library = 'none' | 'swagger1' | 'swagger2' | 'microprofile';\nconst COMBINATIONS: Record<Provider, Library[]> = {\n    none: ['none'],\n    source: ['none', 'swagger1', 'swagger2', 'microprofile'],\n    swagger1: ['swagger1'],\n    swagger2: ['swagger2'],\n    springdoc: ['swagger2'],\n};\nexport function isValidCombination(p: string, l: string): boolean {\n    return p in COMBINATIONS && (COMBINATIONS as Record<string, Library[]>)[p].includes(l as Library);\n}","tryCatchPattern":null,"preventionTips":["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."],"tags":["openapi","java","documentation-provider","annotation-library","configuration"],"backgroundTag":"incompatible-generator-options","analyzedSha":"fcec517be3cf5b7964296bcba25fbc97541484e7","analyzedAt":"2026-08-22T11:13:11.613Z","schemaVersion":2},"datasetVersion":"2026-08-22T14:17:55.899Z"}