zed-industries/zed · error

failed to start screen capture stream

Error message

failed to start screen capture stream: {}

What it means

On macOS, GPUI's screen capture wrapper starts an SCStream and reports failures through an ObjC completion block that receives an NSError. When the stream fails to start, the NSError's localized description is wrapped in this anyhow error and sent back over the channel. It means ScreenCaptureKit refused or failed to begin capturing the requested display/window.

Solutions

  1. Grant the app Screen Recording permission in System Settings > Privacy & Security > Screen Recording, then restart the app.
  2. Re-enumerate displays/windows (SCGetShareableContent) immediately before starting the stream and capture a still-valid ID.
  3. Log the underlying NSError description (it is embedded in the message) to identify the exact ScreenCaptureKit failure.
  4. Retry stream creation once, as ScreenCaptureKit occasionally fails transiently right after permission is granted.

Example fix

// before
let stream = ScreenCaptureStream::new(output, sender);
// after
// check permission / re-enumerate and surface the underlying description
match ScreenCaptureStream::new(output, sender) {
    Ok(stream) => use_stream(stream),
    Err(e) => prompt_screen_recording_permission(&format!("{e:#}")),
}
Defensive patterns

Strategy: try-catch

Validate before calling

fn can_request_screen_capture() -> bool {
    // macOS 12.3+ required for ScreenCaptureKit
    (cfg!(target_os = "macos") && os_version_at_least(12, 3)) || !cfg!(target_os = "macos")
}

Try / catch

match ScreenCaptureStream::new(output, sender) {
    Ok(stream) => stream,
    Err(e) if format!("{e:#}").contains("not permitted") => prompt_for_screen_recording_permission(),
    Err(e) => return Err(anyhow!("screen capture unavailable: {e:#}")),
};

Prevention

When it happens

Trigger: Calling MacScreenCaptureStream::new (via ScreenCaptureStream::new) when SCStreamStartCapture fails: screen recording permission not granted, the captured display/window disappeared, or the SCStream configuration is invalid.

Common situations: App lacks Screen Recording permission in System Settings (or was updated and permission reset); capturing a window that was closed between enumeration and stream start; running on hardware/OS where ScreenCaptureKit rejects the pixel format or configuration.

Related errors

AI-assisted analysis of zed-industries/zed@916fc2b8cb (2026-09-19). Data as JSON: /api/errors/23d177977dd3df60. Report an issue: GitHub.

Appendix: source

Thrown at crates/gpui_macos/src/screen_capture.rs:112

                output_protocol,
                SCStreamOutputType::Screen,
                None,
            ) {
                _ = sender.send(Err(anyhow!(
                    "failed to add stream output: {}",
                    error.localizedDescription()
                )));

                return receiver;
            }

            let state = Rc::new(RefCell::new(Some((sender, stream.clone(), output))));
            let handler = RcBlock::new(move |error: *mut NSError| {
                let Some((sender, stream, output)) = state.borrow_mut().take() else {
                    return;
                };
                let result = if let Some(error) = error.as_ref() {
                    Err(anyhow!(
                        "failed to start screen capture stream: {}",
                        error.localizedDescription()
                    ))
                } else {
                    Ok(Box::new(MacScreenCaptureStream {
                        meta: metadata.clone(),
                        sc_stream: stream,
                        sc_stream_output: output,
                    }) as Box<dyn ScreenCaptureStream>)
                };

                _ = sender.send(result);
            });
            stream.startCaptureWithCompletionHandler(Some(&handler));
        }

        receiver
    }

View on GitHub (pinned to 916fc2b8cb)