hibernate/hibernate-orm · error · IllegalArgumentException

json cannot be null

Error message

json cannot be null

What it means

StringJsonDocumentReader is Hibernate's hand-written pull parser for JSON strings; its constructor rejects a null argument with IllegalArgumentException 'json cannot be null' because the parser needs a concrete document. Hibernate itself short-circuits SQL NULL at the JdbcType/FormatMapper layer before building a reader, so a null reaching this constructor means custom code bypassed that handling.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/type/format/StringJsonDocumentReader.java:42

 * Implementation of <code>JsonDocumentReader</code> for String representation of JSON objects.
 */
public class StringJsonDocumentReader extends StringJsonDocument implements JsonDocumentReader {

	private static final char ESCAPE_CHAR = '\\';

	private final String jsonString;
	private final int limit;
	private int position;
	private int jsonValueStart;
	private int jsonValueEnd;

	/**
	 * Creates a new <code>StringJsonDocumentReader</code>
	 * @param json the JSON String. of the object to be parsed.
	 */
	public StringJsonDocumentReader(String json) {
		if (json == null) {
			throw new IllegalArgumentException( "json cannot be null" );
		}
		this.jsonString = json;
		this.position = 0;
		this.limit = jsonString.length();
		this.jsonValueStart = 0;
		this.jsonValueEnd = 0;
	}

	@Override
	public boolean hasNext() {
		return this.position < this.limit;
	}

	private void skipWhiteSpace() {
		for (;this.position  < this.limit; this.position++ ) {
			if (!Character.isWhitespace( this.jsonString.charAt(this.position))) {
				return;
			}

View on GitHub (pinned to fad1729dce)

Solutions

1. Null-check before constructing: treat null as a null aggregate value instead of parsing
2. Keep SQL-NULL handling in the JdbcType/FormatMapper layer and only build a reader for non-null strings
3. In tests, always pass a sample document string

Example fix

// before
String json = (String) rs.getString(column);
new StringJsonDocumentReader(json); // throws 'json cannot be null' for SQL NULL

// after
String json = rs.getString(column);
if (json == null) { return null; } // null column -> null aggregate
new StringJsonDocumentReader(json);

if (json == null) {
    return null; // SQL NULL -> null aggregate, do not build a reader
}
JsonDocumentReader reader = new StringJsonDocumentReader(json);

When it happens

Trigger: Constructing new StringJsonDocumentReader(null) directly, or custom FormatMapper/adapter code passing a column value that is null without first checking - e.g. reading an aggregate column whose value came back null and forwarding it unchecked.

Common situations: Custom FormatMapper implementations reading aggregates; test code building readers by hand; data flows that skip Hibernate's SQL-NULL handling.

Related errors

• forEachRemaining
• Unsupported type of document reader
• no object key available
• The specified package name cannot be null
• Name of class to load cannot be null

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