OpenAPITools/openapi-generator · error · IllegalArgumentException

Invalid value for additional property 'declarativeInterfaceR

Error message

Invalid value for additional property 'declarativeInterfaceReactiveMode'. Supported values are {values}.

What it means

For library=spring-http-interface with reactive=true, the `declarativeInterfaceReactiveMode` option selects how reactive operations are exposed. The value is parsed with DeclarativeInterfaceReactiveMode.valueOf() (KotlinSpringServerCodegen.java:733), which is case-sensitive and knows exactly two constants: `coroutines` (suspend functions) and `reactor` (Mono/Flux wrappers). Any other string — including uppercase or singular forms — rethrows as an IllegalArgumentException listing the supported values.

Source

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

            if (library.equals(SPRING_DECLARATIVE_HTTP_INTERFACE_LIBRARY)) {
                this.setReactive(convertPropertyToBoolean(REACTIVE));
                if (additionalProperties.containsKey(USE_FLOW_FOR_ARRAY_RETURN_TYPE)) {
                    this.setUseFlowForArrayReturnType(convertPropertyToBoolean(USE_FLOW_FOR_ARRAY_RETURN_TYPE));
                }
                if (this.isUseFlowForArrayReturnType()) {
                    {
                        throw new IllegalArgumentException("Additional property '" + USE_FLOW_FOR_ARRAY_RETURN_TYPE + "' must be set to 'false' as it is not supported by Spring declarative HTTP interface");
                    }
                }
                if (additionalProperties.containsKey(DECLARATIVE_INTERFACE_REACTIVE_MODE)) {
                    try {
                        DeclarativeInterfaceReactiveMode optValue = DeclarativeInterfaceReactiveMode.valueOf(
                                String.valueOf(additionalProperties.get(DECLARATIVE_INTERFACE_REACTIVE_MODE)));
                        setDeclarativeInterfaceReactiveMode(optValue);
                        writePropertyBack(optValue.getAdditionalPropertyName(), true);
                        additionalProperties.remove(DECLARATIVE_INTERFACE_REACTIVE_MODE);
                    } catch (IllegalArgumentException e) {
                        throw new IllegalArgumentException(
                                "Invalid value for additional property '" + DECLARATIVE_INTERFACE_REACTIVE_MODE + "'. Supported values are " + Arrays.toString(DeclarativeInterfaceReactiveMode.values()) + "."
                        );
                    }
                }
            }
        }
        if (SPRING_DECLARATIVE_HTTP_INTERFACE_LIBRARY.equals(library)) {
            if (!isUseSpringBoot4()) {
                this.setUseSpringBoot3(true);
            }
            this.setInterfaceOnly(true);
            this.setUseFeignClient(false);
            this.setSkipDefaultInterface(true);

            writePropertyBack(USE_SPRING_BOOT3, useSpringBoot3);
            writePropertyBack(INTERFACE_ONLY, interfaceOnly);
            writePropertyBack(USE_FEIGN_CLIENT, useFeignClient);
            writePropertyBack(SKIP_DEFAULT_INTERFACE, skipDefaultInterface);

View on GitHub (pinned to fcec517be3)

Solutions

Use exactly `declarativeInterfaceReactiveMode=coroutines` or `declarativeInterfaceReactiveMode=reactor` (lowercase, plural).
Omit the option if the default mode is acceptable.
Check the accepted values for your generator version with `openapi-generator-cli config-help -g kotlin-spring`.

Example fix

# before
openapi-generator-cli generate -g kotlin-spring -i api.yaml \
  --additional-properties library=spring-http-interface,reactive=true,declarativeInterfaceReactiveMode=COROUTINES
# after
openapi-generator-cli generate -g kotlin-spring -i api.yaml \
  --additional-properties library=spring-http-interface,reactive=true,declarativeInterfaceReactiveMode=coroutines

Defensive patterns

Strategy: validation

Validate before calling

// valueOf is case-sensitive; validate before generating
Set<String> modes = Set.of("coroutines", "reactor");
String mode = (String) opts.get("declarativeInterfaceReactiveMode");
if (mode != null && !modes.contains(mode)) {
    throw new IllegalArgumentException(
        "declarativeInterfaceReactiveMode must be exactly one of " + modes + " (lowercase)");
}

Try / catch

try {
    new DefaultGenerator().opts(clientOptInput).generate();
} catch (IllegalArgumentException e) {
    // message enumerates DeclarativeInterfaceReactiveMode.values(); show it to the user verbatim
    throw new BuildException("Invalid kotlin-spring options: " + e.getMessage(), e);
}

Prevention

Note the asymmetry: this option is case-sensitive while documentationProvider/annotationLibrary are not.
Copy enum-valued options from `config-help` output, never from memory or blog posts.
Add a unit test asserting your build's full option set generates successfully.

When it happens

Trigger: Running with `--additional-properties library=spring-http-interface,reactive=true,declarativeInterfaceReactiveMode=COROUTINES` (uppercase), `=coroutine` (singular), `=mono`, or any typo. Only the exact lowercase strings `coroutines` and `reactor` pass.

Common situations: Assuming option values are case-insensitive (unlike documentationProvider/annotationLibrary, which are upper-cased before matching); using singular 'coroutine' because that is the common Kotlin terminology; option names/values drifting between generator versions or blog posts.

Related errors

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