zed-industries/zed · error

instance buffer needs {required} bytes, above the maximum of

Error message

instance buffer needs {required} bytes, above the maximum of {MAX_INSTANCE_BUFFER_SIZE}

What it means

ensure! in MetalRenderer's instance buffer grow(): even after doubling the buffer and rounding to the next power of two, the required size cannot fit under MAX_INSTANCE_BUFFER_SIZE; the frame needs more per-instance GPU data than the renderer can allocate.

Source

Thrown at crates/gpui_apple/src/metal_renderer.rs:1488

    }

    fn write_iter<T>(
        &mut self,
        values: impl ExactSizeIterator<Item = T>,
    ) -> Result<InstanceBinding> {
        let (binding, destination) = self.allocate::<T>(values.len())?;
        for (slot, value) in destination.iter_mut().zip(values) {
            slot.write(value);
        }
        Ok(binding)
    }

    fn grow(&mut self, required: usize) -> Result<()> {
        let mut pool = self.pool.lock();
        let buffer_size = (pool.buffer_size * 2)
            .max(required.next_power_of_two())
            .min(MAX_INSTANCE_BUFFER_SIZE);
        anyhow::ensure!(
            buffer_size >= required,
            "instance buffer needs {required} bytes, above the maximum of {MAX_INSTANCE_BUFFER_SIZE}"
        );
        anyhow::ensure!(
            buffer_size > self.current.size,
            "frame instance data exceeds the {MAX_INSTANCE_BUFFER_SIZE}-byte maximum"
        );
        if buffer_size != pool.buffer_size {
            log::info!("increased instance buffer size to {buffer_size}");
            pool.reset(buffer_size);
        }
        let buffer = pool.acquire(&self.device, self.unified_memory);
        drop(pool);

        let filled = mem::replace(&mut self.current, buffer);
        self.filled.push((filled, self.offset));
        self.offset = 0;
        Ok(())

View on GitHub (pinned to 9d272b0363)

Solutions

1. Reduce per-frame instance data: split draws into multiple passes/batches
2. Investigate excessive primitives (text runs, shadows, quads) in one frame
3. Profile the frame to find the element generating the most instances
4. If legitimately needed, the MAX_INSTANCE_BUFFER_SIZE limit must be raised in the renderer

When it happens

Trigger: Thrown at crates/gpui_apple/src/metal_renderer.rs:1481 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of zed-industries/zed@9d272b0363 (2026-08-20). Data as JSON: /api/errors/e26579c5c360c557. Report an issue: GitHub.