hibernate/hibernate-orm · error · UnsupportedOperationException

Informix does not support binary literals

Error message

Informix does not support binary literals

What it means

InformixDialect.appendBinaryLiteral() throws because Informix SQL has no binary/hex literal syntax that Hibernate could inline. appendBinaryLiteral() is only called when Hibernate decides to render a binary (byte[]) value directly into the SQL text rather than binding it as a JDBC parameter, so this error means a byte[] constant was inlined into the statement.

Source

Thrown at hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/InformixDialect.java:901

				case STRING:
					return "trim(case ?1 when 't' then 'true' when 'f' then 'false' else null end)";
				case TF_BOOLEAN:
					return "upper(cast(?1 as varchar))";
				case YN_BOOLEAN:
					return "case ?1 when 't' then 'Y' when 'f' then 'N' else null end";
				case INTEGER_BOOLEAN:
					return "case ?1 when 't' then 1 when 'f' then 0 else null end";
			}
		}
		if ( from == CastType.STRING && to == CastType.BOOLEAN ) {
			return buildStringToBooleanCast( "'t'", "'f'" );
		}
		return super.castPattern( from, to );
	}

	@Override
	public void appendBinaryLiteral(SqlAppender appender, byte[] bytes) {
		throw new UnsupportedOperationException( "Informix does not support binary literals" );
	}

	@Override
	public String getCatalogSeparator() {
		return ":";
	}

	@Override
	public SqmMultiTableMutationStrategy getFallbackSqmMutationStrategy(
			EntityMappingType rootEntityDescriptor,
			RuntimeModelCreationContext runtimeModelCreationContext) {
		return new LocalTemporaryTableMutationStrategy( rootEntityDescriptor, runtimeModelCreationContext );
	}

	@Override
	public SqmMultiTableInsertStrategy getFallbackSqmInsertStrategy(
			EntityMappingType rootEntityDescriptor,
			RuntimeModelCreationContext runtimeModelCreationContext) {

View on GitHub (pinned to fad1729dce)

Solutions

1. Bind the binary value as a parameter: use a criteria ParameterExpression or HQL :param with setParameter instead of an inlined literal
2. Remove hibernate.query.criteria.literal_handling_mode=inline (default BIND mode keeps byte[] values as JDBC parameters)
3. If the DB design allows, store the binary value as a hex/base64 VARCHAR and compare string literals instead

Example fix

// before - value inlined, calls appendBinaryLiteral on Informix
cb.equal(root.get("contentHash"), hashBytes);

// after - bind as parameter
ParameterExpression<byte[]> p = cb.parameter(byte[].class);
cb.equal(root.get("contentHash"), p);
query.setParameter(p, hashBytes);

// bind binary values instead of inlining them
// criteria: always go through a parameter
ParameterExpression<byte[]> hash = cb.parameter(byte[].class);
Predicate eq = cb.equal(root.get("contentHash"), hash);
// and keep literal handling on the default BIND mode:
// cfg.setProperty(AvailableSettings.CRITERIA_LITERAL_HANDLING_MODE, "bind");

try {
    return session.createQuery(cq).getResultList();
} catch (UnsupportedOperationException e) {
    if ( String.valueOf(e.getMessage()).contains("binary literals") ) {
        // re-issue the query with the value bound as a parameter
    }
    throw e;
}

When it happens

Trigger: A criteria or HQL query that compares or IN-lists a binary column against an inlined byte[] constant on InformixDialect — typically criteria queries with literal handling mode 'inline' (hibernate.query.criteria.literal_handling_mode=inline) or a literal passed where a parameter was expected, e.g. cb.equal(root.get("contentHash"), hashBytes).

Common situations: Entities storing UUID/hashes as byte[] or VARBINARY compared with constants; teams setting criteria literal-handling to inline for execution-plan stability or to work around parameter-length limits; migration of such queries to Informix.

Related errors

• literal value cannot be null
• Connection lock-timeout does not accept skip-locked
• Can't emulate offset clause in subquery
• Summarization is not supported by DBMS!
• Insert conflict 'do update' clause with constraint name is n

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