{"record":{"id":"b21b94e05addc55a","repo":"quarkusio/quarkus","slug":"invalid-orm-compatibility-version-1-s-valid-ver","errorCode":null,"errorMessage":"Invalid ORM compatibility version: %1$s. Valid versions are: %2$s.","messagePattern":"Invalid ORM compatibility version: %1\\$s\\. Valid versions are: %2\\$s\\.","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"extensions/hibernate-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/config/DatabaseOrmCompatibilityVersion.java","lineNumber":102,"sourceCode":"    @Override\n    public String toString() {\n        // Necessary for proper rendering in the documentation\n        return externalRepresentation;\n    }\n\n    public abstract Map<String, String> settings(Optional<String> dbKind);\n\n    public static class Converter\n            implements org.eclipse.microprofile.config.spi.Converter<DatabaseOrmCompatibilityVersion> {\n        @Override\n        public DatabaseOrmCompatibilityVersion convert(String value) {\n            final String normalizedValue = value.trim().toLowerCase(Locale.ROOT);\n            for (DatabaseOrmCompatibilityVersion candidate : values()) {\n                if (candidate.externalRepresentation.equals(normalizedValue)) {\n                    return candidate;\n                }\n            }\n            throw new IllegalArgumentException(String.format(Locale.ROOT,\n                    \"Invalid ORM compatibility version: %1$s. Valid versions are: %2$s.\",\n                    value,\n                    Arrays.stream(values())\n                            .map(v -> v.externalRepresentation)\n                            .collect(Collectors.toList())));\n        }\n    }\n}\n","sourceCodeStart":84,"sourceCodeEnd":111,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/hibernate-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/config/DatabaseOrmCompatibilityVersion.java#L84-L111","documentation":"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.","triggerScenarios":"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.","commonSituations":"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'.","solutions":["Set the property to one of the values listed in the error message (the valid external representations).","Check the current Quarkus docs for quarkus.hibernate-orm.database.orm-compatibility accepted values, since the set can change between versions.","Trim whitespace and mind exact spelling/casing (matching is case-insensitive but spelling must be exact).","If you relied on a removed value, migrate the corresponding behavior manually (e.g. change HQL semantics) instead of via the compat flag."],"exampleFix":"# before\nquarkus.hibernate-orm.database.orm-compatibility=5.x\n\n# after\nquarkus.hibernate-orm.database.orm-compatibility=hibernate-orm-5","handlingStrategy":"validation","validationCode":"// Pre-validate the compat version against accepted values\njava.util.Set<String> valid = java.util.Set.of(\"hibernate-orm-5\"); // see error message for the current list\nString v = configValue.trim().toLowerCase(java.util.Locale.ROOT);\nif (!valid.contains(v)) {\n    throw new IllegalArgumentException(\"Unsupported orm-compatibility: \" + v + \"; valid: \" + valid);\n}","typeGuard":null,"tryCatchPattern":"try {\n    startPu();\n} catch (IllegalArgumentException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"Invalid ORM compatibility version\")) {\n        log.error(\"Use one of the listed valid versions in the error message\", e);\n    }\n    throw e;\n}","preventionTips":["Copy accepted values exactly from the error message or current Quarkus docs","Pin and review orm-compatibility settings when upgrading Quarkus","Let SmallRye Config validation catch bad values in CI by starting the app in tests"],"tags":["hibernate-orm","config","validation","quarkus"],"backgroundTag":"invalid-config-value","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}