hibernate/hibernate-orm · error · QueryParameterException

Space is not allowed after parameter prefix ':'

Error message

Space is not allowed after parameter prefix ':'

What it means

While tokenizing a native SQL string, ParameterParser treats ':' followed by a Java identifier-start character as a named parameter and chops the name at the first separator (space, comma, parenthesis, etc.). If the chopped name comes out empty it throws this QueryParameterException, whose message points at the classic typo of a space between ':' and the parameter name. It is a guard against malformed named-parameter prefixes in native SQL.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/query/sql/internal/ParameterParser.java:136

			else if ( '\'' == c ) {
				inSingleQuotes = true;
				recognizer.other( c );
			}
			// special handling for backslash
			else if ( '\\' == c ) {
				// skip sending the backslash and instead send then next character, treating is as a literal
				recognizer.other( sqlString.charAt( ++indx ) );
			}
			// otherwise
			else {
				if ( c == ':' ) {
					if ( indx < stringLength - 1 && Character.isJavaIdentifierStart( sqlString.charAt( indx + 1 ) ) ) {
						// named parameter
						final int right = StringHelper.firstIndexOfChar( sqlString, HQL_SEPARATORS_BITSET, indx + 1 );
						final int chopLocation = right < 0 ? sqlString.length() : right;
						final String param = sqlString.substring( indx + 1, chopLocation );
						if ( param.isEmpty() ) {
							throw new QueryParameterException(
									"Space is not allowed after parameter prefix ':'",
									sqlString
							);
						}
						recognizer.namedParameter( param, indx );
						indx = chopLocation - 1;
					}
					else {
						// For backwards compatibility, allow some known operators in the escaped form
						if ( indx < stringLength - 3
								&& sqlString.charAt( indx + 1 ) == ':'
								&& sqlString.charAt( indx + 2 ) == ':'
								&& sqlString.charAt( indx + 3 ) == ':' ) {
							// Detect the :: operator, escaped as ::::
							DeprecationLogger.DEPRECATION_LOGGER.deprecatedNativeQueryColonEscaping( "::::", "::" );
							recognizer.other( ':' );
							recognizer.other( ':' );
							indx += 3;

View on GitHub (pinned to fad1729dce)

Solutions

1. Fix the typo: remove whitespace between ':' and the parameter name (':status', not ': status').
2. If the colon is literal SQL (assignment, label), rewrite the SQL to avoid it or use the supported escaped form '::=' which Hibernate passes through.
3. Move literal text containing colons into quoted literals or bind it as a parameter value instead of inlining it.
4. Scan query strings for ':\s' patterns in a build-time test over your SQL resources.

Example fix

-- before
select * from person where status = : status

-- after
select * from person where status = :status

static void validateNamedParameterSyntax(String sql) {
    var m = java.util.regex.Pattern.compile(":\\s+[A-Za-z_$]").matcher(sql);
    if (m.find()) throw new IllegalArgumentException("Whitespace after ':' at index " + m.start() + ": '" + sql.substring(m.start(), Math.min(sql.length(), m.start() + 10)) + "'");
}

try { session.createNativeQuery(sql); } catch (org.hibernate.QueryParameterException e) { /* log sql with position, fix the ':' */ throw e; }

When it happens

Trigger: A native query string containing ': name' style typos, or a stray colon the parser cannot attribute to anything else (e.g. copy-pasted SQL with assignment-style ':=' used without the supported '::=' escape, or colons inside identifiers). Parsing happens as soon as the query is created (session.createNativeQuery / em.createNativeQuery), before execution.

Common situations: Hand-edited SQL templates where a space sneaks in after ':'; MySQL/PostgreSQL procedural syntax (':=') pasted into a native query — modern Hibernate passes ':=' through or expects the '::=' escape; SQL from other tools with templating colons like ':start' left in text.

Related errors

• Named native query definition object is null
• Named native query definition name is null: {}
• Named native query [%s] specified both a resultset-ref and a
• Encountered unexpected content type [%s] for named native qu
• Cannot combine other returns with a collection return (" + r

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