quarkusio/quarkus · error · IllegalArgumentException

Invalid ORM compatibility version: %1$s. Valid versions are:

Error message

Invalid ORM compatibility version: %1$s. Valid versions are: %2$s.

What it means

DatabaseOrmCompatibilityVersion.convert(value) maps a user-provided string (e.g. quarkus.hibernate-orm.database.orm-compatibility) to a version enum by trimming/lowercasing and comparing against each candidate's externalRepresentation. An unrecognized string produces this IllegalArgumentException listing all valid values.

Source

Thrown at extensions/hibernate-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/config/DatabaseOrmCompatibilityVersion.java:102

    @Override
    public String toString() {
        // Necessary for proper rendering in the documentation
        return externalRepresentation;
    }

    public abstract Map<String, String> settings(Optional<String> dbKind);

    public static class Converter
            implements org.eclipse.microprofile.config.spi.Converter<DatabaseOrmCompatibilityVersion> {
        @Override
        public DatabaseOrmCompatibilityVersion convert(String value) {
            final String normalizedValue = value.trim().toLowerCase(Locale.ROOT);
            for (DatabaseOrmCompatibilityVersion candidate : values()) {
                if (candidate.externalRepresentation.equals(normalizedValue)) {
                    return candidate;
                }
            }
            throw new IllegalArgumentException(String.format(Locale.ROOT,
                    "Invalid ORM compatibility version: %1$s. Valid versions are: %2$s.",
                    value,
                    Arrays.stream(values())
                            .map(v -> v.externalRepresentation)
                            .collect(Collectors.toList())));
        }
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

1. Set the property to one of the values listed in the error message (the valid external representations).
2. Check the current Quarkus docs for quarkus.hibernate-orm.database.orm-compatibility accepted values, since the set can change between versions.
3. Trim whitespace and mind exact spelling/casing (matching is case-insensitive but spelling must be exact).
4. If you relied on a removed value, migrate the corresponding behavior manually (e.g. change HQL semantics) instead of via the compat flag.

Example fix

# before
quarkus.hibernate-orm.database.orm-compatibility=5.x

# after
quarkus.hibernate-orm.database.orm-compatibility=hibernate-orm-5

// Pre-validate the compat version against accepted values
java.util.Set<String> valid = java.util.Set.of("hibernate-orm-5"); // see error message for the current list
String v = configValue.trim().toLowerCase(java.util.Locale.ROOT);
if (!valid.contains(v)) {
    throw new IllegalArgumentException("Unsupported orm-compatibility: " + v + "; valid: " + valid);
}

try {
    startPu();
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Invalid ORM compatibility version")) {
        log.error("Use one of the listed valid versions in the error message", e);
    }
    throw e;
}

When it happens

Trigger: Passing a string that does not match any supported external representation, e.g. quarkus.hibernate-orm.database.orm-compatibility=hql-translator-5.x or '5' instead of the exact accepted tokens.

Common situations: Upgrading Quarkus where older compat tokens were removed; copying config from a blog post using an unsupported value; forgetting to lowercase or use the documented format like 'hibernate-orm-5'.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Weigher class '<className>' must implement com.github.benman
• The 'quarkus.hibernate-orm.mapping.format.global' configurat
• Invalid keystore '" + name + "' - The keystore cannot be con
• name cannot be null
• Either location or predicate must be set

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/b21b94e05addc55a. Report an issue: GitHub.