{"record":{"id":"b6f98301b3249171","repo":"phaserjs/phaser","slug":"batchhandlerstrip-vertex-count-exceeds-maximum-pe","errorCode":null,"errorMessage":"BatchHandlerStrip: Vertex count exceeds maximum per batch (","messagePattern":"BatchHandlerStrip: Vertex count exceeds maximum per batch \\(","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/renderer/webgl/renderNodes/BatchHandlerStrip.js","lineNumber":189,"sourceCode":"        vertices,\n        uv,\n        colors,\n        alphas,\n        alpha,\n        tintMode,\n        renderOptions,\n        debugCallback\n    )\n    {\n        if (this.instanceCount === 0)\n        {\n            this.manager.setCurrentBatchNode(this, drawingContext);\n        }\n\n        var submittedInstanceCount = vertices.length / (2 * this.verticesPerInstance);\n        if (submittedInstanceCount > this.instancesPerBatch)\n        {\n            throw new Error('BatchHandlerStrip: Vertex count exceeds maximum per batch (' + this.maxVerticesPerBatch + ')');\n        }\n\n        // Check whether the batch should be rendered immediately.\n        // This guarantees that none of the arrays are full below.\n        if (this.instanceCount + submittedInstanceCount > this.instancesPerBatch)\n        {\n            this.run(drawingContext);\n\n            // Now the batch is empty.\n        }\n\n        // Check render options and run the batch if they differ.\n        renderOptions.alphaStrategy = drawingContext.alphaStrategy;\n        this.updateRenderOptions(renderOptions);\n        if (this._renderOptionsChanged)\n        {\n            this.run(drawingContext);\n            this.updateShaderConfig();","sourceCodeStart":171,"sourceCodeEnd":207,"githubUrl":"https://github.com/phaserjs/phaser/blob/41be1e462bc600064e498cba370bfa8c5c055a22/src/renderer/webgl/renderNodes/BatchHandlerStrip.js#L171-L207","documentation":"Thrown by BatchHandlerStrip when a single addToBatch call passes a vertex array whose computed instance count exceeds instancesPerBatch. The handler batches many instances into one draw call, but it will never split a single submission that is itself larger than the whole batch capacity; that indicates the geometry is too dense for the configured batch size.","triggerScenarios":"Calling the strip batch handler's run/addToBatch with a flat vertex array whose length / (2 * verticesPerInstance) yields more instances than this.instancesPerBatch. Commonly triggered by very large polygon strips or a custom mesh fed in as one submission.","commonSituations":"Rendering oversized particle bursts, large ribbon/trail geometry, or custom strip meshes; lowering batchSize in the game render config below what a single object needs; a bug in a custom batch caller that concatenates many instances into one vertices array instead of submitting them incrementally.","solutions":["Reduce the number of instances passed in a single addToBatch call so it fits within instancesPerBatch (submit in chunks).","Raise instancesPerBatch in the node config, or raise game render config batchSize so the per-batch capacity covers the largest single submission.","If using verticesPerInstance != 2, verify the divisor matches your strip topology so submittedInstanceCount is computed correctly.","Audit the caller to confirm it isn't accidentally accumulating vertices across frames before submitting."],"exampleFix":"// before\nstripNode.run(ctx, { vertices: hugeVertexArray, ... }); // hugeVertexArray too big\n\n// after\nconst CHUNK = stripNode.instancesPerBatch;\nfor (let i = 0; i < hugeVertexArray.length; i += CHUNK * 2 * stripNode.verticesPerInstance) {\n  stripNode.run(ctx, { vertices: hugeVertexArray.subarray(i, i + CHUNK * 2 * stripNode.verticesPerInstance), ... });\n}","handlingStrategy":"validation","validationCode":"const maxPerCall = stripNode.instancesPerBatch;\nconst instances = vertices.length / (2 * stripNode.verticesPerInstance);\nif (instances > maxPerCall) {\n  throw new RangeError(`strip submission ${instances} exceeds ${maxPerCall}; chunk it`);\n}","typeGuard":"function fitsBatch(vertices, node) {\n  const n = vertices.length / (2 * node.verticesPerInstance);\n  return Number.isFinite(n) && n >= 0 && n <= node.instancesPerBatch;\n}","tryCatchPattern":null,"preventionTips":["Chunk large vertex arrays before submission.","Keep batchSize in render config above your largest single object's instance count.","Log vertices.length / divisor during development to catch regressions."],"tags":["renderer","webgl","batching","geometry","phaser4"],"backgroundTag":null,"analyzedSha":"41be1e462bc600064e498cba370bfa8c5c055a22","analyzedAt":"2026-08-13T04:23:39.729Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}