OpenAPITools/openapi-generator · error · RuntimeException

Error preparing constraint for version expression '{requeste

Error message

Error preparing constraint for version expression '{requestedVersion}' treated as major version {asSingleNumber}

What it means

Thrown inside JavaHelidonCommonCodegen's VersionConstraint helper when a requested Helidon version parses as a plain unsigned integer (e.g. "3") — treated as a major version — but building the range constraint "[3,4-alpha)" then fails to parse. It wraps the underlying InvalidVersionSpecificationException, so the message shown is the nested cause's context. In practice this path only fails for Aether/Maven version-scheme inputs that are numeric yet form an invalid range, which is rare.

Source

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

                    }
                }
            }
            // The user might have requested a legal version we cannot fully validate because of a network outage
            // that prevents us from retrieving the current full list of versions, for example. In such cases return the
            // requested version itself as the best match.
            return bestMatch != null ? bestMatch.toString() : requestedVersion;
        }

        private VersionConstraint constraint(VersionScheme versionScheme, String requestedVersion) {
            try {
                int asSingleNumber = Integer.parseUnsignedInt(requestedVersion);
                try {
                    return versionScheme.parseVersionConstraint(String.format(Locale.getDefault(),
                            "[%s,%d-alpha)",
                            requestedVersion,
                            asSingleNumber + 1));
                } catch (InvalidVersionSpecificationException ex) {
                    throw new RuntimeException("Error preparing constraint for version expression '"
                            + requestedVersion
                            + "' treated as major version " + asSingleNumber,
                            ex);
                }
            } catch (NumberFormatException nfe) {
                try {
                    return versionScheme.parseVersionConstraint(requestedVersion);
                } catch (InvalidVersionSpecificationException ex) {
                    throw new RuntimeException("Error parsing version expression '"
                            + requestedVersion
                            + "' as a version constraint",
                            ex);
                }
            }
        }

        /**
         * Retrieves the list of supported versions from the web site or, failing that, local preferences or, failing that,

View on GitHub (pinned to fcec517be3)

Solutions

Specify a concrete version instead of a bare major: helidonVersion=3.2.0
Or use an explicit Maven-style range: helidonVersion="[3.0.0,4.0.0)"
If you need 'latest 3.x', omit helidonVersion and let the generator resolve its default, or pin a known patch release
Upgrade openapi-generator if you hit this with a plain number — constraint building for major-only input has seen fixes

Example fix

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

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

Defensive patterns

Strategy: try-catch

Validate before calling

// Reject bare-number version input before generation
String v = String.valueOf(opts.get("helidonVersion"));
if (v.matches("\\d+")) {
    throw new IllegalArgumentException("helidonVersion must be a full version (e.g. 3.2.0) or Maven range, not a bare number: " + v);
}

Try / catch

try {
    generator.generate();
} catch (RuntimeException e) {
    // VersionConstraint helper failures (constraint preparation) — wrap with the offending input
    if (e.getMessage() != null && e.getMessage().contains("constraint")) {
        throw new IllegalArgumentException("Unparseable helidonVersion '" + opts.get("helidonVersion") + "': use '3.2.0' or '[3.0.0,4.0.0)'", e);
    }
    throw e;
}

Prevention

Always pass full x.y.z Helidon versions in configs; reserve bare majors for docs, not inputs
Centralize version strings in one properties file so CI substitution cannot truncate them
Unit-test your config builder with the exact helidonVersion values it can emit

When it happens

Trigger: Passing --additional-properties helidonVersion=3 (bare major) in an environment where the Aether version scheme rejects the synthesized "[3,4-alpha)" constraint (unusual/custom version schemes, or a requested number so large that asSingleNumber+1 overflows unsigned parse semantics). Typically seen only when the version-resolution helper is also failing to reach its web/local version lists first.

Common situations: Users abbreviating helidonVersion to a single digit expecting 'latest 3.x'. Debug/CI environments with no network where the version-resolution flow behaves differently. This error is a symptom of an unusual version input rather than a mainstream config mistake.

Related errors

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