hibernate/hibernate-orm · error · HibernateException

Enum value converter returned null for enum class '" + enumC

Error message

Enum value converter returned null for enum class '" + enumClass.getName() + "'

What it means

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.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/type/descriptor/converter/internal/EnumHelper.java:57

	}

	public static String[] getEnumeratedValues(Class<? extends Enum<?>> enumClass) {
		final Enum<?>[] values = enumClass.getEnumConstants();
		final String[] names = new String[values.length];
		for ( int i = 0; i < values.length; i++ ) {
			names[i] = values[i].name();
		}
		return names;
	}

	public static String[] getEnumeratedValues(
			Class<? extends Enum<?>> enumClass, BasicValueConverter<Enum<?>,?> converter) {
		final Enum<?>[] values = enumClass.getEnumConstants();
		final String[] names = new String[values.length];
		for ( int i = 0; i < values.length; i++ ) {
			final Object relationalValue = converter.toRelationalValue( values[i] );
			if ( relationalValue == null ) {
				throw new HibernateException( "Enum value converter returned null for enum class '" + enumClass.getName() + "'" );
			}
			names[i] = relationalValue.toString();
		}
		return names;
	}

	public static String[] getSortedEnumeratedValues(Class<? extends Enum<?>> enumClass) {
		final String[] names = getEnumeratedValues( enumClass );
		Arrays.sort( names );
		return names;
	}
}

View on GitHub (pinned to fad1729dce)

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)

Example fix

// before
@Override
public String convertToDatabaseColumn(Status s) {
    return switch (s) {
        case ACTIVE -> "A";
        case CLOSED -> "C";
    }; // future constants fall through to null
}
// after
@Override
public String convertToDatabaseColumn(Status s) {
    return switch (s) {
        case ACTIVE -> "A";
        case CLOSED -> "C";
        default -> "U"; // every constant yields a non-null code
    };
}

Defensive patterns

Strategy: validation

Validate before calling

// self-check at startup or in a schema-export test: every constant must map to non-null
for (Status s : Status.values()) {
    if (converter.convertToDatabaseColumn(s) == null) {
        throw new IllegalStateException("Converter returns null for " + s);
    }
}

Type guard

static boolean mapsAllConstants(Function<Status, ?> fn) {
    return Arrays.stream(Status.values()).map(fn).allMatch(Objects::nonNull);
}

Try / catch

try {
    new SchemaExport().createOnly(EnumSet.of(TargetType.DATABASE), metadata);
} catch (HibernateException e) {
    if (String.valueOf(e.getMessage()).contains("returned null for enum class")) {
        // add the missing case to the converter, then re-run export
    } else throw e;
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of hibernate/hibernate-orm@fad1729dce (2026-08-22). Data as JSON: /api/errors/0d1e964982b0cbd0. Report an issue: GitHub.