BabylonJS/Babylon.js · error

Unable to create instance buffer

Error message

Unable to create instance buffer

What it means

createInstancesBuffer() calls the underlying WebGL context's createBuffer(); when the GL driver fails to allocate a buffer (returns null) the engine throws this error. It almost always indicates GPU/driver resource exhaustion or a lost context, since instance buffers are ordinary GL buffer objects.

Source

Thrown at packages/dev/core/src/Engines/engine.pure.ts:977

                gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_COMPARE_MODE, gl.COMPARE_REF_TO_TEXTURE);
            }

            this._bindTextureDirectly(this._gl.TEXTURE_2D, null);
        }

        texture._comparisonFunction = comparisonFunction;
    }

    /**
     * Creates a webGL buffer to use with instantiation
     * @param capacity defines the size of the buffer
     * @returns the webGL buffer
     */
    public createInstancesBuffer(capacity: number): DataBuffer {
        const buffer = this._gl.createBuffer();

        if (!buffer) {
            throw new Error("Unable to create instance buffer");
        }

        const result = new WebGLDataBuffer(buffer);
        result.capacity = capacity;

        this.bindArrayBuffer(result);
        this._gl.bufferData(this._gl.ARRAY_BUFFER, capacity, this._gl.DYNAMIC_DRAW);

        result.references = 1;

        return result;
    }

    /**
     * Delete a webGL buffer used with instantiation
     * @param buffer defines the webGL buffer to delete
     */
    public deleteInstancesBuffer(buffer: WebGLBuffer): void {

View on GitHub (pinned to 0592b347b8)

Solutions

1. Check whether the WebGL context is lost (gl.isContextLost()) and re-initialize the engine before creating instance buffers.
2. Reduce the number/capacity of live GPU buffers and dispose unused ones (buffer.dispose()) before allocating.
3. Add a context-loss handler and recreate resources on restore.
4. Retry the allocation after freeing resources.

Example fix

// before
const instBuf = engine.createInstancesBuffer(4 * floats);
// after
if (engine._gl.isContextLost()) {
  engine.dispose();
  engine = new Engine(canvas, true);
}
const instBuf = engine.createInstancesBuffer(4 * floats);

if (engine._gl.isContextLost()) {
  throw new Error("skip: context lost, recreate engine first");
}

function canAllocateBuffers(engine) {
  const gl = engine._gl;
  return !!gl && !gl.isContextLost();
}

try {
  instanceBuffer = engine.createInstancesBuffer(capacity);
} catch (e) {
  if (/Unable to create instance buffer/.test(e.message)) {
    disposeUnusedBuffers(engine);
    instanceBuffer = engine.createInstancesBuffer(capacity);
  }
}

When it happens

Trigger: engine.createInstancesBuffer(capacity) when gl.createBuffer() returns null — context is lost, or the driver has run out of buffer allocations / memory.

Common situations: Creating buffers after a webglcontextlost event, extremely large capacity requests exhausting GPU memory, embedded/mobile drivers with strict buffer limits, or too many live buffers never released.

Related errors

• Unable to create multi sampled framebuffer
• Unable to create program
• Unable to create vertex buffer
• Unable to create index buffer
• Atmosphere is not supported on WebGL ${engine.version}.

AI-assisted analysis of BabylonJS/Babylon.js@0592b347b8 (2026-08-30). Data as JSON: /api/errors/aefa7bf6cc91662e. Report an issue: GitHub.