What causes "Helidon version %s uses the %s namespace but options specified '%s'" in OpenAPITools/openapi-generator?

Match the namespace to the version: helidon 4.x -> rootJavaEEPackage=jakarta, helidon 3.x -> rootJavaEEPackage=javax

OpenAPITools/openapi-generator · error · IllegalArgumentException

Helidon version %s uses the %s namespace but options specifi

Error message

Helidon version %s uses the %s namespace but options specified '%s'

What it means

Thrown by JavaHelidonCommonCodegen.checkAndSelectRootEEPackage when the user-set rootJavaEEPackage property disagrees with the namespace implied by the chosen Helidon version. Helidon 3.x and earlier use the javax.* MicroProfile root package; Helidon 4.x uses jakarta.*. Because generated imports, pom dependencies, and templates all key off this prefix, an inconsistent override is rejected instead of silently producing broken code.

Source

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

            useOptional = true;
        } else if (useOptionalSetting instanceof Boolean) {
            useOptional = (Boolean) useOptionalSetting;
        } else if (useOptionalSetting instanceof String) {
            useOptional = Boolean.parseBoolean((String) useOptionalSetting);
        }
        additionalProperties.put(X_USE_OPTIONAL, useOptional);
    }

    private String checkAndSelectRootEEPackage(String version) {
        String packagePrefixImpliedByVersion = usesJakartaPackages(version)
                ? MICROPROFILE_ROOT_PACKAGE_JAKARTA
                : MICROPROFILE_ROOT_PACKAGE_JAVAX;

        // Make sure any user-specified root EE package is correct for the chosen Helidon version.
        if (additionalProperties.containsKey(MICROPROFILE_ROOT_PACKAGE)) {
            String userRootEEPackage = additionalProperties.get(MICROPROFILE_ROOT_PACKAGE).toString();
            if (!packagePrefixImpliedByVersion.equals(userRootEEPackage)) {
                throw new IllegalArgumentException(
                        String.format(Locale.ROOT,
                                "Helidon version %s uses the %s namespace but options specified '%s'",
                                version,
                                packagePrefixImpliedByVersion,
                                userRootEEPackage));
            }
            return userRootEEPackage;
        }

        // No explicit setting for the root EE package.
        return packagePrefixImpliedByVersion;
    }

    private String checkAndSelectRootEEDepPrefix(String version) {
        String mavenDepPrefixImpliedByVersion = usesJakartaPrefix(version)
                ? MICROPROFILE_ROOT_PACKAGE_JAKARTA
                : MICROPROFILE_ROOT_PACKAGE_JAVAX;

View on GitHub (pinned to fcec517be3)

Solutions

Match the namespace to the version: helidon 4.x -> rootJavaEEPackage=jakarta, helidon 3.x -> rootJavaEEPackage=javax
Simplest: remove the rootJavaEEPackage property and let the generator derive it from helidonVersion
If you must keep javax, downgrade helidonVersion to a 3.x release
After a version bump, grep your config templates for stale rootJavaEEPackage entries in CI presets

Example fix

# before
openapi-generator-cli generate -g java-helidon-server -i api.yaml \
  --additional-properties helidonVersion=4.1.0,rootJavaEEPackage=javax

# after
openapi-generator-cli generate -g java-helidon-server -i api.yaml \
  --additional-properties helidonVersion=4.1.0,rootJavaEEPackage=jakarta

Defensive patterns

Strategy: validation

Validate before calling

String helidonVersion = String.valueOf(opts.get("helidonVersion"));
String expected = helidonVersion.startsWith("4") || helidonVersion.startsWith("3.0") == false && helidonVersion.startsWith("3") == false ? "jakarta" : "javax";
// simpler, matching generator logic: 4.x -> jakarta, else javax
expected = helidonVersion.startsWith("4") ? "jakarta" : "javax";
String user = (String) opts.get("rootJavaEEPackage");
if (user != null && !user.equals(expected)) {
    throw new IllegalArgumentException("rootJavaEEPackage=" + user + " conflicts with helidonVersion=" + helidonVersion + " (needs " + expected + ")");
}

Try / catch

try {
    generator.generate();
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().contains("namespace")) {
        // namespace/version conflict — instruct user to align rootJavaEEPackage or drop it
        throw new ConfigException("Jakarta/javax mismatch: " + e.getMessage(), e);
    }
    throw e;
}

Prevention

Never set rootJavaEEPackage manually; let helidonVersion drive the namespace
Automate Helidon upgrades by grepping configs for javax/jakarta literals after a version bump
When both rootJavaEEPackage and x-helidon-rootJavaEEDepPrefix appear in a config, validate they agree with the version in a pre-flight check

When it happens

Trigger: Passing --additional-properties helidonVersion=4.1.0,rootJavaEEPackage=javax (or helidonVersion=3.2.0,rootJavaEEPackage=jakarta) to -g java-helidon-server or -g java-helidon-client. Also triggered when upgrading helidonVersion from 3.x to 4.x in a config file that already pinned rootJavaEEPackage=javax for the old stack.

Common situations: Migrating a Helidon 3 service to Helidon 4: the config that used to need an explicit javax override now conflicts with the jakarta default. Teams targeting legacy javax runtimes on new Helidon versions (unsupported combination) hit it deliberately and must downgrade Helidon instead.

Related errors

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