hibernate/hibernate-orm · error · IllegalArgumentException

Missing parameter index in pattern: '<pattern>'

Error message

Missing parameter index in pattern: '<pattern>'

What it means

PatternRenderer compiles the SQL pattern of a pattern-based function descriptor. Placeholders are written as '?' immediately followed by the 1-based argument number (?1, ?2, ...). parameterIndex throws IllegalArgumentException('Missing parameter index...') when the pattern contains a bare '?' with no digits after it. The exception fires when the renderer is constructed - i.e. at function registration during startup - so the application fails to boot or the dialect fails to initialize.

Source

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

		if ( !chunk.isEmpty() ) {
			chunkList.add( chunk.toString() );
		}

		this.varargParam = vararg;
		this.maxParamIndex = max;

		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;

View on GitHub (pinned to fad1729dce)

Solutions

1. Number every placeholder in the pattern: ?1, ?2, ... (repeat a number to render the same argument twice).
2. If a '?' is meant literally (e.g. a JSON operator), restructure the pattern so no bare '?' remains next to the placeholder syntax.
3. Construct the renderer in a unit test for every registered pattern so the failure happens in CI, not at boot.

Example fix

// before - JDBC-style placeholders, no indexes
new PatternBasedSqmFunctionDescriptor(..., "nvl(?, ?)", ...)

// after - numbered placeholders
new PatternBasedSqmFunctionDescriptor(..., "nvl(?1, ?2)", ...)

static void assertPatternPlaceholders(String pattern) {
    for (int i = 0; i < pattern.length(); i++) {
        if (pattern.charAt(i) == '?'
                && (i + 1 >= pattern.length() || !Character.isDigit(pattern.charAt(i + 1)))) {
            throw new IllegalArgumentException("Bare '?' at index " + 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: Registering a function whose SQL pattern uses JDBC-style bare placeholders, e.g. "nvl(?, ?)" or "coalesce(?,?)" instead of Hibernate's "nvl(?1, ?2)"; or a trailing '?' at the end of a pattern like "mod(?1, ?)".

Common situations: Porting native SQL snippets verbatim into pattern-based registrations; Hibernate 5 to 6 migration where patterns must now use numbered placeholders; typos introduced while editing long SQL patterns.

Related errors

• Illegal parameter index '<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/af1308a3b1914e6c. Report an issue: GitHub.