hibernate/hibernate-orm · error · MappingException

Column with logical name '%s' in table '%s' cannot be mapped

Error message

Column with logical name '%s' in table '%s' cannot be mapped to column identifier

What it means

getPhysicalColumnName(Table, String) converts the logical column name to an Identifier before lookup; getDatabase().toIdentifier(...) returns null for a null/blank name, and that null triggers this MappingException. It is effectively a null-argument guard on the logical-column resolution path, reached almost exclusively through programmatic or custom mapping code.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/internal/InFlightMetadataCollectorImpl.java:1150

			binding = null;
		}
		else {
			binding = columnNameBindingByTableMap.get( table );
		}

		if ( binding == null ) {
			binding = new TableColumnNameBinding( table.getName() );
			columnNameBindingByTableMap.put( table, binding );
		}

		binding.addBinding( logicalName, column );
	}

	@Override
	public String getPhysicalColumnName(Table table, String logicalName) throws MappingException {
		final Identifier identifier = getDatabase().toIdentifier( logicalName );
		if ( identifier == null ) {
			throw new MappingException( String.format(
					Locale.ENGLISH,
					"Column with logical name '%s' in table '%s' cannot be mapped to column identifier",
					logicalName,
					table.getName()
			) );
		}
		return getPhysicalColumnName( table, identifier );
	}

	@Override
	public String getPhysicalColumnName(Table table, Identifier logicalName) throws MappingException {
		if ( logicalName == null ) {
			throw new MappingException( "Logical column name cannot be null" );
		}

		Table currentTable = table;
		while ( currentTable != null ) {
			final TableColumnNameBinding binding = columnNameBindingByTableMap.get( currentTable );

View on GitHub (pinned to fad1729dce)

Solutions

1. Null/blank-check the logical name before calling the API
2. Validate column names when mappings are read so the malformed entry is named at load time
3. Log table plus property context during column-name resolution so the offending mapping is identifiable

Example fix

// before
String physical = mapping.getPhysicalColumnName( table, columnName );

// after
if ( columnName == null || columnName.isBlank() ) {
    throw new IllegalStateException( "Missing logical column name for table " + table.getName() );
}
String physical = mapping.getPhysicalColumnName( table, columnName );

if ( logicalName == null || logicalName.isBlank() ) {
    throw new IllegalStateException( "Missing logical column name for table " + table.getName() );
}
return mapping.getPhysicalColumnName( table, logicalName );

static boolean isResolvableLogicalColumnName( String logicalName ) {
    return logicalName != null && !logicalName.isBlank();
}

try {
    return mapping.getPhysicalColumnName( table, logicalName );
} catch ( MappingException e ) {
    if ( e.getMessage() != null && e.getMessage().contains( "cannot be mapped to column identifier" ) ) {
        throw new IllegalStateException( "Null/blank logical column name for table " + table.getName(), e );
    }
    throw e;
}

When it happens

Trigger: Calling this mapping API with a null or blank logical column name: dynamic components with null keys, custom binders resolving a column name that was never set, or mapping generators emitting empty column names.

Common situations: Custom MetadataContributors, dynamic-map entities with malformed component keys, and code-generated mappings that leave column names empty for optional elements.

Related errors

• Named query definition is null
• Named native query definition object is null
• Result-set mapping was null
• Import name or entity name is null
• Table [%s] contains logical column name [%s] referring to mu

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