{"record":{"id":"d48a99ca96e5ca4f","repo":"hibernate/hibernate-orm","slug":"ioexception-occurred-reading-a-binary-value-d48a99","errorCode":null,"errorMessage":"IOException occurred reading a binary value","messagePattern":"IOException occurred reading a binary value","errorType":"exception","errorClass":"HibernateException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/type/descriptor/java/DataHelper.java","lineNumber":125,"sourceCode":"\t\t\tint charsRead = 0;\n\t\t\twhile ( true ) {\n\t\t\t\tfinal int amountRead = characterStream.read( buffer, 0, bufferSize );\n\t\t\t\tif ( amountRead == -1 ) {\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t\tstringBuilder.append( buffer, 0, amountRead );\n\t\t\t\tif ( amountRead < bufferSize ) {\n\t\t\t\t\t// we have read up to the end of stream\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t\tcharsRead += amountRead;\n\t\t\t\tif ( charsRead >= length ) {\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\tcatch ( IOException ioe ) {\n\t\t\tthrow new HibernateException( \"IOException occurred reading a binary value\", ioe );\n\t\t}\n\t\treturn stringBuilder.toString();\n\t}\n\n\t/**\n\t * Extract a portion of a reader, wrapping the portion in a new reader.\n\t *\n\t * @param characterStream The reader for the content\n\t * @param start The start position/offset (0-based, per general stream/reader contracts).\n\t * @param length The amount to extract\n\t *\n\t * @return The content portion as a reader\n\t */\n\tpublic static Reader subStream(Reader characterStream, long start, int length) {\n\t\treturn new StringReader( extractString( characterStream, start, length ) );\n\t}\n\n\t/**","sourceCodeStart":107,"sourceCodeEnd":143,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/type/descriptor/java/DataHelper.java#L107-L143","documentation":"Same read loop as the whole-stream variant, but inside extractString(Reader, long start, int length): any IOException raised while reading characters after a successful skip is wrapped as HibernateException. The message says 'binary value' although this path reads characters — a copy-paste artifact in DataHelper; treat it as a text-stream failure.","triggerScenarios":"Partial CLOB reads (start/length) where the stream breaks mid-read: connection reset, the LOB was invalidated by an intervening commit, or the driver tied the stream's lifetime to a ResultSet that was already closed.","commonSituations":"Reading substring-shaped LOB data on Oracle/PostgreSQL; racing session close or commit against the read; network drops during extraction.","solutions":["Extract LOB portions immediately on the live ResultSet, inside the open transaction","Retry the read once in a fresh transaction — transient IO failures are common here","Classify via getCause() (timeout vs closed vs reset) and tune socket/statement timeouts or driver settings accordingly","Prefer full reads plus in-memory substring over stream skipping"],"exampleFix":"// before: reader obtained from an earlier ResultSet, session since closed\nString part = extractString(reader, start, len); // IOException mid-read\n\n// after: perform the extraction on the live ResultSet/session scope\nString all = clob.getSubString(1, (int) clob.length());","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    return extractPortion(clob, start, length);\n} catch (HibernateException e) {\n    if (e.getCause() instanceof IOException) {\n        // re-open in a fresh transaction and retry once, then surface\n    }\n}","preventionTips":["Extract LOB portions immediately on the live ResultSet","Do not cache Readers across requests or transactions","Close sessions only after LOB materialization completes"],"tags":["hibernate","lob","clob","io","misleading-message"],"backgroundTag":"lob-stream-read-ioexception","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}