OpenAPITools/openapi-generator · error · IllegalArgumentException

Helidon version %s uses the %s prefix for EE dependencies bu

Error message

Helidon version %s uses the %s prefix for EE dependencies but options specified '%s'

What it means

Thrown by JavaHelidonCommonCodegen.checkAndSelectRootEEDepPrefix when the user-set x-helidon-rootJavaEEDepPrefix (the Maven artifactId prefix for EE dependencies) disagrees with the prefix implied by the Helidon version: jakarta for Helidon 4.x, javax for Helidon 3.x. This controls Maven groupId/artifact prefixes such as jakarta.json.bind vs javax.json.bind in the generated pom. It is the dependency-side twin of the rootJavaEEPackage check (error 127).

Source

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

                                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;

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

        // No explicit setting for the dependency prefix.
        return mavenDepPrefixImpliedByVersion;
    }

    private boolean usesJakartaPackages(String version) {
        return !version.startsWith("2.") && !version.startsWith("1.");
    }

    private boolean usesJakartaPrefix(String version) {

View on GitHub (pinned to fcec517be3)

Solutions

Match the prefix to the version: helidon 4.x -> x-helidon-rootJavaEEDepPrefix=jakarta, helidon 3.x -> javax
Best: delete the x-helidon-rootJavaEEDepPrefix property so the generator derives it from helidonVersion
Keep x-helidon-rootJavaEEDepPrefix and rootJavaEEPackage consistent with each other whenever both are set
If javax prefixes are required, pin helidonVersion to 3.x instead of forcing the prefix on 4.x

Example fix

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

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

Defensive patterns

Strategy: validation

Validate before calling

String helidonVersion = String.valueOf(opts.get("helidonVersion"));
String expected = helidonVersion.startsWith("4") ? "jakarta" : "javax";
String depPrefix = (String) opts.get("x-helidon-rootJavaEEDepPrefix");
if (depPrefix != null && !depPrefix.equals(expected)) {
    throw new IllegalArgumentException("x-helidon-rootJavaEEDepPrefix=" + depPrefix + " conflicts with helidonVersion=" + helidonVersion + " (needs " + expected + ")");
}

Try / catch

try {
    generator.generate();
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().contains("EE dependencies")) {
        throw new ConfigException("Helidon dep-prefix/namespace mismatch: " + e.getMessage(), e);
    }
    throw e;
}

Prevention

Avoid setting the x-helidon-rootJavaEEDepPrefix advanced property unless a downstream build strictly requires it
Keep namespace-related options (rootJavaEEPackage, x-helidon-rootJavaEEDepPrefix, helidonVersion) in one config block and review them together
Add a smoke generation step in CI to catch option drift before release pipelines hit it

When it happens

Trigger: Passing --additional-properties helidonVersion=4.1.0,x-helidon-rootJavaEEDepPrefix=javax (or the inverse for 3.x) to the Helidon server/client generators. Happens when a config pins the dep prefix for an older stack and helidonVersion is later bumped, or when both x-helidon-rootJavaEEDepPrefix and rootJavaEEPackage are hand-tuned inconsistently.

Common situations: Migration from Helidon 3 to 4 where CI configuration files carry the old javax prefix. Rarely hit by accident — this is an advanced (x- prefixed, undocumented-ish) property usually present only in carefully customized builds, so its presence almost always means a hand-tuned config that drifted from the chosen version.

Related errors

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