{"record":{"id":"0c91b03abb5e2a30","repo":"OpenAPITools/openapi-generator","slug":"the-s-documentation-provider-does-not-support-0c91b0","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/KotlinSpringServerCodegen.java","lineNumber":548,"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        if (additionalProperties.containsKey(USE_SPRING_BOOT3)) {\n            this.setUseSpringBoot3(convertPropertyToBoolean(USE_SPRING_BOOT3));\n        }\n        if (additionalProperties.containsKey(USE_SPRING_BOOT4)) {\n            this.setUseSpringBoot4(convertPropertyToBoolean(USE_SPRING_BOOT4));\n        }\n        if (additionalProperties.containsKey(USE_SPRING_BUILT_IN_VALIDATION)) {\n            this.setUseSpringBuiltInValidation(convertPropertyToBoolean(USE_SPRING_BUILT_IN_VALIDATION));","sourceCodeStart":530,"sourceCodeEnd":566,"githubUrl":"https://github.com/OpenAPITools/openapi-generator/blob/fcec517be3cf5b7964296bcba25fbc97541484e7/modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/KotlinSpringServerCodegen.java#L530-L566","documentation":"Each DocumentationProvider declares which annotation libraries it can be combined with: springdoc only pairs with swagger2, while none/source pair with any library (DocumentationProviderFeatures.java:64-78). Even when both individual values are supported by kotlin-spring, processOpts() rejects incompatible pairs with an IllegalArgumentException. This is a cross-option consistency check that runs after the two individual checks.","triggerScenarios":"Running `-g kotlin-spring` with `--additional-properties documentationProvider=springdoc,annotationLibrary=swagger1` (or annotationLibrary=none with springdoc). springdoc's supportedAnnotationLibraries() contains only SWAGGER2, so any other pairing with springdoc throws at KotlinSpringServerCodegen.java:548.","commonSituations":"Migrating a legacy swagger1-annotated kotlin-spring project to springdoc while keeping the old annotationLibrary flag; setting annotationLibrary explicitly because an example did so, without realizing springdoc implies swagger2; partially edited CI option lists.","solutions":["With `documentationProvider=springdoc`, use `annotationLibrary=swagger2` or simply omit annotationLibrary (it defaults to the provider's preferred library).","If you must keep swagger1 annotations, switch the provider: `documentationProvider=source` (or `none`), which supports all annotation libraries.","Audit the full option string for stale provider/annotation pairs after upgrading the generator."],"exampleFix":"# before\nopenapi-generator-cli generate -g kotlin-spring -i api.yaml \\\n  --additional-properties documentationProvider=springdoc,annotationLibrary=swagger1\n# after\nopenapi-generator-cli generate -g kotlin-spring -i api.yaml \\\n  --additional-properties documentationProvider=springdoc,annotationLibrary=swagger2","handlingStrategy":"validation","validationCode":"// mirror the provider->library pairing table before generating\nMap<String, Set<String>> allowed = Map.of(\n    \"SPRINGDOC\", Set.of(\"SWAGGER2\"),\n    \"NONE\",      Set.of(\"NONE\", \"SWAGGER1\", \"SWAGGER2\"),\n    \"SOURCE\",    Set.of(\"NONE\", \"SWAGGER1\", \"SWAGGER2\"));\nString dp = String.valueOf(opts.getOrDefault(\"documentationProvider\", \"SPRINGDOC\")).toUpperCase(Locale.ROOT);\nString al = String.valueOf(opts.getOrDefault(\"annotationLibrary\", \"SWAGGER2\")).toUpperCase(Locale.ROOT);\nif (!allowed.getOrDefault(dp, Set.of()).contains(al)) {\n    throw new IllegalArgumentException(dp + \" cannot be combined with \" + al);\n}","typeGuard":null,"tryCatchPattern":"try {\n    new DefaultGenerator().opts(clientOptInput).generate();\n} catch (IllegalArgumentException e) {\n    // message states the unsupported combination; surface it with the valid pairings\n    throw new BuildException(\"Invalid kotlin-spring options: \" + e.getMessage(), e);\n}","preventionTips":["Set documentationProvider only, and let annotationLibrary default to its preferred value.","When changing providers, delete the old annotationLibrary flag instead of overwriting blindly.","Keep a tested, known-good option string per project and diff against it in code review."],"tags":["kotlin","spring","springdoc","annotation-library","option-combination","openapi-generator","config-validation"],"backgroundTag":"incompatible-option-combination","analyzedSha":"fcec517be3cf5b7964296bcba25fbc97541484e7","analyzedAt":"2026-08-22T11:13:11.613Z","schemaVersion":2},"datasetVersion":"2026-08-22T14:17:55.899Z"}