OpenAPITools/openapi-generator · error · IllegalArgumentException

You cannot combine [returnResponse] and [returnJBossResponse

Error message

You cannot combine [returnResponse] and [returnJBossResponse] since they are mutually exclusive

What it means

Thrown by JavaJAXRSSpecServerCodegen.processOpts (quarkus library branch) when returnResponse=true and returnJBossResponse=true at the same time. The two flags select different response wrapper types for generated endpoint signatures — javax.ws.rs.core.Response vs org.jboss.resteasy.reactive.RestResponse — and templates can only emit one signature style. The check runs inside the quarkus supporting-file setup, so it only applies with --library quarkus.

Source

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

                fileName = openApiSpecFileLocation;
            }
            supportingFiles.add(new SupportingFile("openapi.mustache", fileFolder, fileName));
        }

        if (QUARKUS_LIBRARY.equals(library)) {
            supportingFiles.add(new SupportingFile("application.properties.mustache", "src/main/resources", "application.properties")
                    .doNotOverwrite());
            supportingFiles.add(new SupportingFile("Dockerfile.jvm.mustache", "src/main/docker", "Dockerfile.jvm")
                    .doNotOverwrite());
            supportingFiles.add(new SupportingFile("Dockerfile.native.mustache", "src/main/docker", "Dockerfile.native")
                    .doNotOverwrite());
            supportingFiles.add(new SupportingFile("dockerignore.mustache", "", ".dockerignore")
                    .doNotOverwrite());
            if(returnResponse && returnJbossResponse) {
              String msg = String.format(Locale.ROOT,
                  "You cannot combine [%s] and [%s] since they are mutually exclusive",
                  RETURN_RESPONSE, RETURN_JBOSS_RESPONSE);
              throw new IllegalArgumentException(msg);
            }
            if(returnJbossResponse && !useJakartaEe) {
              String msg = String.format(Locale.ROOT,
                  "The [%s] requires [%s] to be true, because org.jboss.resteasy.reactive.RestResponse was introduced in Quarkus 2.x",
                  RETURN_JBOSS_RESPONSE, USE_JAKARTA_EE);
              throw new IllegalArgumentException(msg);
            }
        } else if (OPEN_LIBERTY_LIBRARY.equals(library)) {
            supportingFiles.add(new SupportingFile("server.xml.mustache", "src/main/liberty/config", "server.xml")
                    .doNotOverwrite());
            supportingFiles.add(new SupportingFile("beans.xml.mustache", "src/main/webapp/META-INF", "beans.xml")
                    .doNotOverwrite());
            supportingFiles.add(new SupportingFile("MANIFEST.MF.mustache", "src/main/webapp/META-INF", "MANIFEST.MF")
                    .doNotOverwrite());
            supportingFiles.add(new SupportingFile("microprofile-config.properties.mustache", "src/main/webapp/META-INF", "microprofile-config.properties")
                    .doNotOverwrite());
            supportingFiles.add(new SupportingFile("ibm-web-ext.xml.mustache", "src/main/webapp/WEB-INF", "ibm-web-ext.xml")
                    .doNotOverwrite());

View on GitHub (pinned to fcec517be3)

Solutions

Choose one response style: for RESTEasy Reactive use returnJBossResponse=true and remove returnResponse (also set useJakartaEe=true, see error 138)
For plain JAX-RS Response signatures keep returnResponse=true and remove returnJBossResponse
Grep stored configs and CI pipelines for both keys; keep exactly one
When migrating response styles, do flag swaps atomically in the same commit to avoid mixed states

Example fix

# before
openapi-generator-cli generate -g jaxrs-jersey -i api.yaml --library quarkus \
  --additional-properties returnResponse=true,returnJBossResponse=true

# after
openapi-generator-cli generate -g jaxrs-jersey -i api.yaml --library quarkus \
  --additional-properties returnJBossResponse=true,useJakartaEe=true

Defensive patterns

Strategy: validation

Validate before calling

boolean returnResponse = Boolean.parseBoolean(String.valueOf(opts.getOrDefault("returnResponse", "false")));
boolean returnJBoss = Boolean.parseBoolean(String.valueOf(opts.getOrDefault("returnJBossResponse", "false")));
if (returnResponse && returnJBoss) {
    throw new IllegalArgumentException("returnResponse and returnJBossResponse are mutually exclusive");
}

Try / catch

try {
    generator.generate();
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().contains("mutually exclusive")) {
        throw new ConfigException("Choose one response wrapper: returnResponse (JAX-RS Response) or returnJBossResponse (RestResponse)", e);
    }
    throw e;
}

Prevention

Expose a single 'responseStyle=response|jboss' setting in your wrapper and map it to exactly one flag
During RESTEasy Reactive migration, remove returnResponse in the same commit that adds returnJBossResponse
Lint quarkus configs for flag pairs known to conflict (response wrappers, annotation systems)

When it happens

Trigger: Passing --additional-properties returnResponse=true,returnJBossResponse=true to -g jaxrs-jersey --library quarkus. Happens when a config that already used returnResponse gains the newer returnJBossResponse during a Quarkus/RESTEasy Reactive migration without removing the old flag.

Common situations: Adopting RESTEasy Reactive (Quarkus 2.x+): teams add returnJBossResponse=true to get RestResponse signatures but leave returnResponse=true from the previous setup. Shared config presets accumulate response-style flags over time.

Related errors

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