What causes "Unique suffix [%s] length must be less than maximum [%d]" in hibernate/hibernate-orm?

Shorten column names via @Column so no truncation is needed.

hibernate/hibernate-orm · error · MappingException

Unique suffix [%s] length must be less than maximum [%d]

Error message

Unique suffix [%s] length must be less than maximum [%d]

What it means

When Hibernate must shorten a column alias to honor dialect.getMaxAliasLength(), it appends a short unique suffix to keep aliases distinct. If the suffix itself is at least as long as the maximum alias length, no valid alias can be produced and bootstrap fails with this MappingException.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/mapping/Column.java:227

		else {
			final String lowerCaseName = name.toLowerCase( Locale.ROOT );
			return lowerCaseName.length() > lastLetter + 1
					? lowerCaseName.substring( 0, lastLetter + 1 )
					: lowerCaseName;
		}
	}

	private @Nonnull String qualifyAlias(Dialect dialect, String suffix, String alias) {
		final int suffixLength = suffix.length();
		final int maxAliasLength = dialect.getMaxAliasLength();
		final int freeLength = maxAliasLength - suffixLength;
		final boolean useRawName =
				name.length() <= freeLength
				&& !quoted
				&& !name.equalsIgnoreCase( dialect.rowId(null) );
		if ( !useRawName ) {
			if ( suffixLength >= maxAliasLength ) {
				throw new MappingException(
						String.format(
								"Unique suffix [%s] length must be less than maximum [%d]",
								suffix, maxAliasLength
						)
				);
			}
			if ( alias.length() > freeLength ) {
				return alias.substring( 0, freeLength ) + suffix;
			}
		}
		return alias + suffix;
	}

	/**
	 * Generate a column alias that is unique across multiple tables
	 */
	@Override
	public String getAlias(Dialect dialect, Table table) {

View on GitHub (pinned to fad1729dce)

Solutions

Shorten column names via @Column so no truncation is needed.
Use or extend a current dialect matching the actual database version so getMaxAliasLength() reports correctly.
As a last resort, override alias generation in a custom dialect.

Example fix

// before (12-char alias budget)
@Column(name = "customer_primary_contact_telephone")
private String primaryContactPhone;

// after
@Column(name = "prim_phone")
private String primaryContactPhone;

Defensive patterns

Strategy: validation

Validate before calling

int maxAlias = dialect.getMaxAliasLength();
// keep generated column names comfortably below maxAlias to avoid truncated-alias suffixing
if ( columnName.length() + 4 >= maxAlias ) {
    log.warn( "Column name {} is close to alias limit {}", columnName, maxAlias );
}

Prevention

Keep column names short by convention (@Column with concise names)
Run schema export and query smoke tests against the production dialect in CI
Use a dialect version that matches the actual database

When it happens

Trigger: A dialect with a very small maxAliasLength (or a custom dialect misreporting it) combined with long or quoted column names that force the truncation path; rowid-like names; many duplicate truncated aliases producing longer generated suffixes.

Common situations: Oracle-family dialects (12/30-character limits) with very long generated names from long entity/field names; applications extending an outdated Oracle dialect; result set mappings selecting many similarly-named columns.

Related errors

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