hibernate/hibernate-orm · error · IllegalArgumentException

Illegal parameter index '<index>' in pattern: '<pattern>'

Error message

Illegal parameter index '<index>' in pattern: '<pattern>'

What it means

The same PatternRenderer.parameterIndex parse step: after '?', the index text is parsed with Integer.parseInt, and a NumberFormatException is chained into IllegalArgumentException('Illegal parameter index ...') when that text is not a plain integer. Like the missing-index case, this fails when the renderer is built, i.e. during function registration at startup.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/query/sqm/produce/function/internal/PatternRenderer.java:138

		this.chunks = chunkList.toArray( EMPTY_STRING_ARRAY );
		int[] paramIndexes = new int[paramList.size()];
		for ( i = 0; i < paramIndexes.length; ++i ) {
			paramIndexes[i] = paramList.get( i );
		}
		this.paramIndexes = paramIndexes;
		this.argumentRenderingModes = argumentRenderingModes;
	}

	private static int parameterIndex(String pattern, String index) {
		if ( index.isEmpty() ) {
			throw new IllegalArgumentException( "Missing parameter index in pattern: '" + pattern + "'" );
		}
		final int paramNumber;
		try {
			paramNumber = parseInt( index );
		}
		catch (NumberFormatException nfe) {
			throw new IllegalArgumentException( "Illegal parameter index '" + index
												+ "' in pattern: '" + pattern + "'", nfe );
		}
		return paramNumber;
	}

	public boolean hasVarargs() {
		return varargParam >= 0;
	}

	public int getParamCount() {
		return maxParamIndex;
	}

	/**
	 * The rendering code.
	 *
	 * @param sqlAppender Target for appending
	 * @param args The arguments to inject into the template

View on GitHub (pinned to fad1729dce)

Solutions

1. Fix the placeholder to a plain integer index: ?2.
2. If text was intended right after a placeholder, move it outside the placeholder token: "(?1, ?2)" instead of "(?1, ?2d)".
3. Add a construction-time test for every registered pattern so bad indexes fail the build.

Example fix

// before
"date_trunc(?unit, ?1)"

// after
"date_trunc(?2, ?1)"

static void assertPatternIndexes(String pattern) {
    for (int i = 0; i < pattern.length(); i++) {
        if (pattern.charAt(i) != '?') continue;
        int j = i + 1;
        while (j < pattern.length() && Character.isDigit(pattern.charAt(j))) j++;
        boolean empty = (j == i + 1);
        boolean gluedLetter = j < pattern.length() && Character.isLetter(pattern.charAt(j));
        if (empty || gluedLetter) {
            throw new IllegalArgumentException("Bad parameter index at char " + i + " in pattern: " + pattern);
        }
    }
}

try {
    new PatternRenderer(pattern);
} catch (IllegalArgumentException e) {
    throw new IllegalStateException("Bad SQL pattern for function '" + name + "': '" + pattern + "'", e);
}

When it happens

Trigger: A pattern whose placeholder index part is not a pure integer: "date_trunc(?unit, ?1)", "trunc(?1, ?start)", or an index glued to letters like '?1x'.

Common situations: Typos when hand-editing patterns; template substitution that mangles placeholder numbers; mixing PostgreSQL-style $1 placeholders with '?' placeholders in one pattern.

Related errors

• Missing parameter index in pattern: '<pattern>'
• Passed `invariantType` for function return cannot be null
• Passed `invariantType` for function return cannot be null
• Passed `selectionExpression` for function return cannot be n
• Passed `component` for function return cannot be null

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