{"record":{"id":"c965b377a6787e0b","repo":"hibernate/hibernate-orm","slug":"illegal-null-value-for-array-index-encountered-whi","errorCode":null,"errorMessage":"Illegal null value for array index encountered while reading: ","messagePattern":"Illegal null value for array index encountered while reading: ","errorType":"exception","errorClass":"HibernateException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/sql/results/graph/collection/internal/ArrayInitializer.java","lineNumber":86,"sourceCode":"\tprotected void forEachSubInitializer(BiConsumer<Initializer<?>, RowProcessingState> consumer, InitializerData data) {\n\t\tsuper.forEachSubInitializer( consumer, data );\n\t\tfinal var initializer = elementAssembler.getInitializer();\n\t\tif ( initializer != null ) {\n\t\t\tconsumer.accept( initializer, data.getRowProcessingState() );\n\t\t}\n\t}\n\n\t@Override\n\tpublic @Nullable PersistentArrayHolder<?> getCollectionInstance(ImmediateCollectionInitializerData data) {\n\t\treturn (PersistentArrayHolder<?>) super.getCollectionInstance( data );\n\t}\n\n\t@Override\n\tprotected void readCollectionRow(ImmediateCollectionInitializerData data, List<Object> loadingState) {\n\t\tfinal var rowProcessingState = data.getRowProcessingState();\n\t\tfinal Integer indexValue = listIndexAssembler.assemble( rowProcessingState );\n\t\tif ( indexValue == null ) {\n\t\t\tthrow new HibernateException( \"Illegal null value for array index encountered while reading: \"\n\t\t\t\t\t+ getCollectionAttributeMapping().getNavigableRole() );\n\t\t}\n\t\tfinal Object element = elementAssembler.assemble( rowProcessingState );\n\t\tif ( element == null ) {\n\t\t\t// If element is null, then NotFoundAction must be IGNORE\n\t\t\treturn;\n\t\t}\n\t\tint index = indexValue;\n\n\t\tif ( indexBase != 0 ) {\n\t\t\tindex -= indexBase;\n\t\t}\n\n\t\tfor ( int i = loadingState.size(); i <= index; ++i ) {\n\t\t\tloadingState.add( i, null );\n\t\t}\n\n\t\tloadingState.set( index, element );","sourceCodeStart":68,"sourceCodeEnd":104,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/sql/results/graph/collection/internal/ArrayInitializer.java#L68-L104","documentation":"For array-mapped collections (primitive/object arrays), each row's position is assembled from the index column (adjusted for indexBase). ArrayInitializer.readCollectionRow throws HibernateException 'Illegal null value for array index encountered while reading' plus the collection's navigable role when that index value assembles to null - arrays cannot hold a null index, so the row is unusable. Null elements are tolerated (NotFound handling); null indexes are not.","triggerScenarios":"Reading an array-mapped collection whose index column (@OrderColumn/@IndexColumn, or the idx column of the join table) contains NULL in some rows; mapping mistakes where the configured index column is nullable or is the wrong column entirely.","commonSituations":"Manually inserted or ETL-loaded join-table rows without index values; join tables written by legacy code leaving idx null; @OrderColumn naming the wrong column; data migrated from a system that had no array ordering.","solutions":["Fix the data: populate non-null, contiguous index values for the affected collection rows","Add a NOT NULL constraint on the index column so bad rows cannot re-enter","Verify the @OrderColumn/@IndexColumn mapping names the real index column and that indexBase matches how data was written","Backfill outside Hibernate if the table was populated by other tooling: UPDATE t SET idx = <row_number per owner> WHERE idx IS NULL"],"exampleFix":"// mapping under scrutiny\n@OneToMany\n@OrderColumn( name = \"idx\", nullable = false )\nprivate LineItem[] items;\n\n-- repair data so the index is never null\nUPDATE OrderLines SET idx = (SELECT COUNT(*) FROM OrderLines o2\n  WHERE o2.order_id = OrderLines.order_id AND o2.id < OrderLines.id)\nWHERE idx IS NULL;","handlingStrategy":"validation","validationCode":"-- run before relying on an array-mapped collection: no null indexes allowed\nSELECT owner_id FROM join_table WHERE index_column IS NULL;\n-- any rows returned must be repaired first","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Declare the index/order column NOT NULL for array mappings","Verify @OrderColumn/@IndexColumn names the real index column and indexBase matches written data","Backfill null indexes after bulk/ETL loads before first read"],"tags":["hibernate","orm","array-mapping","data-integrity","collection"],"backgroundTag":"collection-index-null","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}