{"record":{"id":"7c7163845ce631b6","repo":"hibernate/hibernate-orm","slug":"json-cannot-be-null","errorCode":null,"errorMessage":"json cannot be null","messagePattern":"json cannot be null","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/type/format/StringJsonDocumentReader.java","lineNumber":42,"sourceCode":" * Implementation of <code>JsonDocumentReader</code> for String representation of JSON objects.\n */\npublic class StringJsonDocumentReader extends StringJsonDocument implements JsonDocumentReader {\n\n\tprivate static final char ESCAPE_CHAR = '\\\\';\n\n\tprivate final String jsonString;\n\tprivate final int limit;\n\tprivate int position;\n\tprivate int jsonValueStart;\n\tprivate int jsonValueEnd;\n\n\t/**\n\t * Creates a new <code>StringJsonDocumentReader</code>\n\t * @param json the JSON String. of the object to be parsed.\n\t */\n\tpublic StringJsonDocumentReader(String json) {\n\t\tif (json == null) {\n\t\t\tthrow new IllegalArgumentException( \"json cannot be null\" );\n\t\t}\n\t\tthis.jsonString = json;\n\t\tthis.position = 0;\n\t\tthis.limit = jsonString.length();\n\t\tthis.jsonValueStart = 0;\n\t\tthis.jsonValueEnd = 0;\n\t}\n\n\t@Override\n\tpublic boolean hasNext() {\n\t\treturn this.position < this.limit;\n\t}\n\n\tprivate void skipWhiteSpace() {\n\t\tfor (;this.position  < this.limit; this.position++ ) {\n\t\t\tif (!Character.isWhitespace( this.jsonString.charAt(this.position))) {\n\t\t\t\treturn;\n\t\t\t}","sourceCodeStart":24,"sourceCodeEnd":60,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/type/format/StringJsonDocumentReader.java#L24-L60","documentation":"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.","triggerScenarios":"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.","commonSituations":"Custom FormatMapper implementations reading aggregates; test code building readers by hand; data flows that skip Hibernate's SQL-NULL handling.","solutions":["Null-check before constructing: treat null as a null aggregate value instead of parsing","Keep SQL-NULL handling in the JdbcType/FormatMapper layer and only build a reader for non-null strings","In tests, always pass a sample document string"],"exampleFix":"// before\nString json = (String) rs.getString(column);\nnew StringJsonDocumentReader(json); // throws 'json cannot be null' for SQL NULL\n\n// after\nString json = rs.getString(column);\nif (json == null) { return null; } // null column -> null aggregate\nnew StringJsonDocumentReader(json);","handlingStrategy":"validation","validationCode":"if (json == null) {\n    return null; // SQL NULL -> null aggregate, do not build a reader\n}\nJsonDocumentReader reader = new StringJsonDocumentReader(json);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Handle SQL NULL before parsing in custom mappers/adapters","Let Hibernate's JdbcType layer own null handling; only build readers for non-null strings","Unit-test custom FormatMappers against null column values"],"tags":["hibernate","json","null-check","document-reader"],"backgroundTag":"null-argument","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}