phaserjs/phaser · error · Error

BatchHandler must have a name

Error message

BatchHandler must have a name

What it means

Thrown by the BatchHandler render node constructor when its config has no 'name' property after _copyAndCompleteConfig runs. Every RenderNode (the base class) requires a name to register with the RenderNodeManager, so a batch handler without one cannot be created. The name is what getNode/addNode use to look the node up later, so an empty/falsy name is a hard stop rather than a defaultable value.

Source

Thrown at src/renderer/webgl/renderNodes/BatchHandler.js:47

 * @extends Phaser.Renderer.WebGL.RenderNodes.RenderNode
 * @param {Phaser.Renderer.WebGL.RenderNodes.RenderNodeManager} manager - The manager that owns this RenderNode.
 * @param {Phaser.Types.Renderer.WebGL.RenderNodes.BatchHandlerConfig} defaultConfig - The default configuration object for this RenderNode. This is used to ensure all required properties are present, so it must be complete.
 * @param {Phaser.Types.Renderer.WebGL.RenderNodes.BatchHandlerConfig} [config] - The configuration object for this RenderNode.
 */
var BatchHandler = new Class({
    Extends: RenderNode,

    initialize: function BatchHandler (manager, defaultConfig, config)
    {
        var renderer = manager.renderer;
        var gl = renderer.gl;

        config = this._copyAndCompleteConfig(manager, config || {}, defaultConfig);

        var name = config.name;
        if (!name)
        {
            throw new Error('BatchHandler must have a name');
        }

        RenderNode.call(this, name, manager);

        /**
         * The number of instances per batch, used to determine the size of the
         * vertex buffer, and the number of instances to render.
         *
         * This is usually limited by the maximum number of vertices that can be
         * distinguished with a 16-bit UNSIGNED_INT index buffer,
         * which is 65536. This is set in the game render config as `batchSize`.
         *
         * @name Phaser.Renderer.WebGL.RenderNodes.BatchHandler#instancesPerBatch
         * @type {number}
         * @since 4.0.0
         */
        this.instancesPerBatch = -1;

View on GitHub (pinned to 41be1e462b)

Solutions

1. Provide a 'name' string in the config passed to the BatchHandler constructor (or in the subclass defaultConfig), e.g. config.name = 'MyBatchHandler'.
2. If registering via RenderNodeManager.addNodeConstructor/getNode, ensure the registration name flows into config.name.
3. Audit any BatchHandler subclass's defaultConfig to confirm it sets a name.
4. If you do not need a custom node, use one of the built-in BatchHandler subclasses which already define names.

Example fix

// before
manager.addNodeConstructor('MyBatch', function (manager) {
  return new BatchHandler(manager, {}, {}); // missing name
});

// after
manager.addNodeConstructor('MyBatch', function (manager) {
  return new BatchHandler(manager, {}, { name: 'MyBatch' });
});

function ensureBatchHandlerName(config) {
  if (!config || typeof config.name !== 'string' || config.name.length === 0) {
    throw new TypeError('BatchHandler config.name must be a non-empty string');
  }
  return config;
}

function isBatchHandlerConfig(c) {
  return c != null && typeof c === 'object' && typeof c.name === 'string' && c.name.length > 0;
}

try {
  node = new BatchHandler(manager, defaultCfg, cfg);
} catch (e) {
  if (/must have a name/.test(e.message)) { /* fix config.name and retry or report */ }
  else throw e;
}

When it happens

Trigger: Constructing a BatchHandler (or subclass like BatchHandlerQuad, BatchHandlerTri) directly or via RenderNodeManager.addNode/getNode with a config object where 'name' is undefined, null, or empty string. Happens when a custom BatchHandler subclass overrides defaultConfig but omits the name key, or when a node constructor is registered and instantiated without a config.name being supplied by the caller.

Common situations: Authoring a custom render node in Phaser 4's new render-graph system and forgetting the 'name' field in the node config; copy-pasting a BatchHandler subclass and stripping the name; migrating from Phaser 3 where names were implicit.

Related errors

• node
• node constructor
• OES_standard_derivatives extension not supported. Cannot use
• BatchHandlerStrip: Vertex count exceeds maximum per batch (
• BaseFilterShader: No fragment shader source provided and no

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