{"record":{"id":"a2925862d9e3cecf","repo":"mrdoob/three.js","slug":"three-batchedmesh-instance-ids-outside-the-range","errorCode":null,"errorMessage":"THREE.BatchedMesh: Instance ids outside the range ${ maxInstanceCount } are being used. Cannot shrink instance count.","messagePattern":"THREE\\.BatchedMesh: Instance ids outside the range (.+?) are being used\\. Cannot shrink instance count\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/objects/BatchedMesh.js","lineNumber":1282,"sourceCode":"\t * @param {number} maxInstanceCount - The max number of individual instances that can be added and rendered by the batch.\n\t*/\n\tsetInstanceCount( maxInstanceCount ) {\n\n\t\t// shrink the available instances as much as possible\n\t\tconst availableInstanceIds = this._availableInstanceIds;\n\t\tconst instanceInfo = this._instanceInfo;\n\t\tavailableInstanceIds.sort( ascIdSort );\n\t\twhile ( availableInstanceIds[ availableInstanceIds.length - 1 ] === instanceInfo.length - 1 ) {\n\n\t\t\tinstanceInfo.pop();\n\t\t\tavailableInstanceIds.pop();\n\n\t\t}\n\n\t\t// throw an error if it can't be shrunk to the desired size\n\t\tif ( maxInstanceCount < instanceInfo.length ) {\n\n\t\t\tthrow new Error( `THREE.BatchedMesh: Instance ids outside the range ${ maxInstanceCount } are being used. Cannot shrink instance count.` );\n\n\t\t}\n\n\t\t// copy the multi draw counts\n\t\tconst multiDrawCounts = new Int32Array( maxInstanceCount );\n\t\tconst multiDrawStarts = new Int32Array( maxInstanceCount );\n\t\tcopyArrayContents( this._multiDrawCounts, multiDrawCounts );\n\t\tcopyArrayContents( this._multiDrawStarts, multiDrawStarts );\n\n\t\tthis._multiDrawCounts = multiDrawCounts;\n\t\tthis._multiDrawStarts = multiDrawStarts;\n\t\tthis._maxInstanceCount = maxInstanceCount;\n\n\t\t// update texture data for instance sampling\n\t\tconst indirectTexture = this._indirectTexture;\n\t\tconst matricesTexture = this._matricesTexture;\n\t\tconst colorsTexture = this._colorsTexture;\n","sourceCodeStart":1264,"sourceCodeEnd":1300,"githubUrl":"https://github.com/mrdoob/three.js/blob/da05705fa31f02710c19772a2aa70c7454807f0c/src/objects/BatchedMesh.js#L1264-L1300","documentation":"Thrown by BatchedMesh.setInstanceCount() when you request a maxInstanceCount smaller than the number of instances currently in use. setInstanceCount can only shrink down to instanceInfo.length after popping trailing unused slots; if any active instance occupies an ID >= the requested count, shrinking is refused.","triggerScenarios":"Calling batchedMesh.setInstanceCount(n) where n is less than the highest in-use instance ID + 1. Common when instances were added with addInstance up to high IDs and you then attempt to lower the capacity without first deleting the high-id instances.","commonSituations":"Trying to free memory by lowering instance capacity while instances still reference those high slots; computing the new count from a live-instance count that excludes still-allocated high IDs.","solutions":["Delete or compact instances so the highest in-use ID is below maxInstanceCount before calling setInstanceCount.","Call deleteGeometry/addInstance in an order that keeps IDs dense, or re-create the BatchedMesh at the desired capacity.","Query the actual required count (highest active instance id + 1) and only shrink to that floor.","If you must shrink aggressively, build a new BatchedMesh and migrate active instances."],"exampleFix":"// before\nbatch.addInstance( 5, geoId, matrix ); // high id in use\nbatch.setInstanceCount( 3 ); // throws: id 5 >= 3\n\n// after\nbatch.deleteInstance( 5 );\nbatch.addInstance( 1, geoId, matrix ); // re-add into a low slot\nbatch.setInstanceCount( 3 );","handlingStrategy":"validation","validationCode":"// Compute the floor: highest in-use instance id + 1.\nlet highest = -1;\nfor ( let i = 0; i < batchedMesh._instanceInfo.length; i++ ) {\n  if ( batchedMesh._instanceInfo[ i ].active ) highest = i;\n}\nconst floor = highest + 1;\nif ( newCount >= floor ) batchedMesh.setInstanceCount( newCount );","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Delete high-id instances before lowering capacity.","Keep instance IDs dense by reusing freed low slots.","Compute the required floor (highest active id + 1) before shrinking.","If aggressive shrinking is required, migrate instances into a fresh BatchedMesh."],"tags":["batchedmesh","resize","instances","capacity"],"backgroundTag":null,"analyzedSha":"da05705fa31f02710c19772a2aa70c7454807f0c","analyzedAt":"2026-08-12T22:51:37.160Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}