phaserjs/phaser · error · Error

BatchHandlerStrip: Vertex count exceeds maximum per batch (

Error message

BatchHandlerStrip: Vertex count exceeds maximum per batch (

What it means

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.

Source

Thrown at src/renderer/webgl/renderNodes/BatchHandlerStrip.js:189

        vertices,
        uv,
        colors,
        alphas,
        alpha,
        tintMode,
        renderOptions,
        debugCallback
    )
    {
        if (this.instanceCount === 0)
        {
            this.manager.setCurrentBatchNode(this, drawingContext);
        }

        var submittedInstanceCount = vertices.length / (2 * this.verticesPerInstance);
        if (submittedInstanceCount > this.instancesPerBatch)
        {
            throw new Error('BatchHandlerStrip: Vertex count exceeds maximum per batch (' + this.maxVerticesPerBatch + ')');
        }

        // Check whether the batch should be rendered immediately.
        // This guarantees that none of the arrays are full below.
        if (this.instanceCount + submittedInstanceCount > this.instancesPerBatch)
        {
            this.run(drawingContext);

            // Now the batch is empty.
        }

        // Check render options and run the batch if they differ.
        renderOptions.alphaStrategy = drawingContext.alphaStrategy;
        this.updateRenderOptions(renderOptions);
        if (this._renderOptionsChanged)
        {
            this.run(drawingContext);
            this.updateShaderConfig();

View on GitHub (pinned to 41be1e462b)

Solutions

1. Reduce the number of instances passed in a single addToBatch call so it fits within instancesPerBatch (submit in chunks).
2. Raise instancesPerBatch in the node config, or raise game render config batchSize so the per-batch capacity covers the largest single submission.
3. If using verticesPerInstance != 2, verify the divisor matches your strip topology so submittedInstanceCount is computed correctly.
4. Audit the caller to confirm it isn't accidentally accumulating vertices across frames before submitting.

Example fix

// before
stripNode.run(ctx, { vertices: hugeVertexArray, ... }); // hugeVertexArray too big

// after
const CHUNK = stripNode.instancesPerBatch;
for (let i = 0; i < hugeVertexArray.length; i += CHUNK * 2 * stripNode.verticesPerInstance) {
  stripNode.run(ctx, { vertices: hugeVertexArray.subarray(i, i + CHUNK * 2 * stripNode.verticesPerInstance), ... });
}

const maxPerCall = stripNode.instancesPerBatch;
const instances = vertices.length / (2 * stripNode.verticesPerInstance);
if (instances > maxPerCall) {
  throw new RangeError(`strip submission ${instances} exceeds ${maxPerCall}; chunk it`);
}

function fitsBatch(vertices, node) {
  const n = vertices.length / (2 * node.verticesPerInstance);
  return Number.isFinite(n) && n >= 0 && n <= node.instancesPerBatch;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• BatchHandler must have a name
• node
• node constructor
• BaseFilterShader: No fragment shader source provided and no
• Color attachments must have the same dimensions

AI-assisted analysis of phaserjs/phaser@41be1e462b (2026-08-13). Data as JSON: /api/errors/b6f98301b3249171. Report an issue: GitHub.