{"record":{"id":"562b838a014aa187","repo":"mrdoob/three.js","slug":"three-batchedmesh-maximum-item-count-reached","errorCode":null,"errorMessage":"THREE.BatchedMesh: Maximum item count reached.","messagePattern":"THREE\\.BatchedMesh: Maximum item count reached\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/objects/BatchedMesh.js","lineNumber":568,"sourceCode":"\t\t}\n\n\t}\n\n\t/**\n\t * Adds a new instance to the batch using the geometry of the given ID and returns\n\t * a new id referring to the new instance to be used by other functions.\n\t *\n\t * @param {number} geometryId - The ID of a previously added geometry via {@link BatchedMesh#addGeometry}.\n\t * @return {number} The instance ID.\n\t */\n\taddInstance( geometryId ) {\n\n\t\tconst atCapacity = this._instanceInfo.length >= this.maxInstanceCount;\n\n\t\t// ensure we're not over geometry\n\t\tif ( atCapacity && this._availableInstanceIds.length === 0 ) {\n\n\t\t\tthrow new Error( 'THREE.BatchedMesh: Maximum item count reached.' );\n\n\t\t}\n\n\t\tconst instanceInfo = {\n\t\t\tvisible: true,\n\t\t\tactive: true,\n\t\t\tgeometryIndex: geometryId,\n\t\t};\n\n\t\tlet drawId = null;\n\n\t\t// Prioritize using previously freed instance ids\n\t\tif ( this._availableInstanceIds.length > 0 ) {\n\n\t\t\tthis._availableInstanceIds.sort( ascIdSort );\n\n\t\t\tdrawId = this._availableInstanceIds.shift();\n\t\t\tthis._instanceInfo[ drawId ] = instanceInfo;","sourceCodeStart":550,"sourceCodeEnd":586,"githubUrl":"https://github.com/mrdoob/three.js/blob/da05705fa31f02710c19772a2aa70c7454807f0c/src/objects/BatchedMesh.js#L550-L586","documentation":"Thrown by BatchedMesh.addInstance() when `_instanceInfo.length >= maxInstanceCount` AND there are no freed ids available in `_availableInstanceIds`. The batch is statically sized by the maxInstanceCount constructor argument; once full (and with no deletions to recycle ids), no further instances can be added.","triggerScenarios":"Calling addInstance() more than maxInstanceCount times without deleting any; constructing BatchedMesh with too small a maxInstanceCount for the scene; deleting nothing and continuing to add.","commonSituations":"Underestimating instance count at construction; growing a scene beyond the pre-allocated batch size; spawning entities dynamically without freeing dead ones.","solutions":["Construct BatchedMesh with a maxInstanceCount large enough for the maximum expected instances (plus headroom).","Recycle instances: call deleteInstance() for dead entities before adding new ones.","If the cap is structurally wrong, rebuild the BatchedMesh with a larger maxInstanceCount (call setInstanceCount to grow it, or recreate)."],"exampleFix":"// before\nconst batch = new BatchedMesh( 100, vertexCount );\nfor ( let i = 0; i < 150; i ++ ) batch.addInstance( geomId ); // throws at 100\n\n// after\nconst batch = new BatchedMesh( 200, vertexCount );\nfor ( let i = 0; i < 150; i ++ ) batch.addInstance( geomId );","handlingStrategy":"validation","validationCode":"function canAddInstance( batch ) {\n  const atCapacity = batch._instanceInfo.length >= batch.maxInstanceCount;\n  return ! atCapacity || batch._availableInstanceIds.length > 0;\n}\n\nif ( ! canAddInstance( batch ) ) throw new Error( 'BatchedMesh is at capacity; delete instances or raise maxInstanceCount.' );","typeGuard":"const hasInstanceCapacity = ( batch ) => canAddInstance( batch );","tryCatchPattern":"try {\n  batch.addInstance( geometryId );\n} catch ( e ) {\n  if ( /Maximum item count reached/.test( e.message ) ) {\n    batch.deleteInstance( recycledId ); // free a slot then retry\n    batch.addInstance( geometryId );\n  } else throw e;\n}","preventionTips":["Size maxInstanceCount with headroom for peak entity count.","Recycle dead instances via deleteInstance() before adding new ones.","Grow the batch (setInstanceCount or recreate) if the cap is structurally too low."],"tags":["batched-mesh","capacity","instance","configuration"],"backgroundTag":null,"analyzedSha":"da05705fa31f02710c19772a2aa70c7454807f0c","analyzedAt":"2026-08-12T22:51:37.160Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}