{"record":{"id":"0d1e964982b0cbd0","repo":"hibernate/hibernate-orm","slug":"enum-value-converter-returned-null-for-enum-class","errorCode":null,"errorMessage":"Enum value converter returned null for enum class '\" + enumClass.getName() + \"'","messagePattern":"Enum value converter returned null for enum class '\" \\+ enumClass\\.getName\\(\\) \\+ \"'","errorType":"exception","errorClass":"HibernateException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/type/descriptor/converter/internal/EnumHelper.java","lineNumber":57,"sourceCode":"\t}\n\n\tpublic static String[] getEnumeratedValues(Class<? extends Enum<?>> enumClass) {\n\t\tfinal Enum<?>[] values = enumClass.getEnumConstants();\n\t\tfinal String[] names = new String[values.length];\n\t\tfor ( int i = 0; i < values.length; i++ ) {\n\t\t\tnames[i] = values[i].name();\n\t\t}\n\t\treturn names;\n\t}\n\n\tpublic static String[] getEnumeratedValues(\n\t\t\tClass<? extends Enum<?>> enumClass, BasicValueConverter<Enum<?>,?> converter) {\n\t\tfinal Enum<?>[] values = enumClass.getEnumConstants();\n\t\tfinal String[] names = new String[values.length];\n\t\tfor ( int i = 0; i < values.length; i++ ) {\n\t\t\tfinal Object relationalValue = converter.toRelationalValue( values[i] );\n\t\t\tif ( relationalValue == null ) {\n\t\t\t\tthrow new HibernateException( \"Enum value converter returned null for enum class '\" + enumClass.getName() + \"'\" );\n\t\t\t}\n\t\t\tnames[i] = relationalValue.toString();\n\t\t}\n\t\treturn names;\n\t}\n\n\tpublic static String[] getSortedEnumeratedValues(Class<? extends Enum<?>> enumClass) {\n\t\tfinal String[] names = getEnumeratedValues( enumClass );\n\t\tArrays.sort( names );\n\t\treturn names;\n\t}\n}\n","sourceCodeStart":39,"sourceCodeEnd":70,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/type/descriptor/converter/internal/EnumHelper.java#L39-L70","documentation":"Thrown by EnumHelper.getEnumeratedValues when generating native ENUM DDL (PostgreSQL/Oracle/GaussDB enum SQL types): Hibernate runs every enum constant through the mapped BasicValueConverter (an AttributeConverter) to collect the string form for the CREATE TYPE / CHECK constraint, and a converter returned null for at least one constant.","triggerScenarios":"An @Enumerated enum attribute with an applied AttributeConverter, on a dialect with native enum type support, where convertToDatabaseColumn returns null for some enum constant - typically a switch missing a case or an explicit null mapping.","commonSituations":"Adding a new enum constant without extending the converter; a converter that maps an 'UNKNOWN' constant to null; enabling native enum DDL (e.g. PostgreSQL enum support) on a schema that previously stored plain integers/strings; schema validation/export (hbm2ddl) after a converter change.","solutions":["Make convertToDatabaseColumn return a non-null value for every enum constant (add default case; map UNKNOWN to a sentinel code)","Run schema export only after the converter covers all constants","If null is a legitimate mapping, disable native enum DDL for that column (e.g. @JdbcTypeCode(SqlTypes.VARCHAR) or the dialect's enum support setting)"],"exampleFix":"// before\n@Override\npublic String convertToDatabaseColumn(Status s) {\n    return switch (s) {\n        case ACTIVE -> \"A\";\n        case CLOSED -> \"C\";\n    }; // future constants fall through to null\n}\n// after\n@Override\npublic String convertToDatabaseColumn(Status s) {\n    return switch (s) {\n        case ACTIVE -> \"A\";\n        case CLOSED -> \"C\";\n        default -> \"U\"; // every constant yields a non-null code\n    };\n}","handlingStrategy":"validation","validationCode":"// self-check at startup or in a schema-export test: every constant must map to non-null\nfor (Status s : Status.values()) {\n    if (converter.convertToDatabaseColumn(s) == null) {\n        throw new IllegalStateException(\"Converter returns null for \" + s);\n    }\n}","typeGuard":"static boolean mapsAllConstants(Function<Status, ?> fn) {\n    return Arrays.stream(Status.values()).map(fn).allMatch(Objects::nonNull);\n}","tryCatchPattern":"try {\n    new SchemaExport().createOnly(EnumSet.of(TargetType.DATABASE), metadata);\n} catch (HibernateException e) {\n    if (String.valueOf(e.getMessage()).contains(\"returned null for enum class\")) {\n        // add the missing case to the converter, then re-run export\n    } else throw e;\n}","preventionTips":["Add a default arm to every enum converter switch returning a sentinel code","Write a startup assertion iterating enum values through the converter","Add new enum constants and converter cases in the same commit","Run hbm2ddl export in CI so native enum DDL generation is exercised"],"tags":["hibernate","orm","jpa","enum","attribute-converter","schema-export","ddl"],"backgroundTag":"enum-converter-null-mapping","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}