{"record":{"id":"23d177977dd3df60","repo":"zed-industries/zed","slug":"failed-to-start-screen-capture-stream","errorCode":null,"errorMessage":"failed to start screen capture stream: {}","messagePattern":"failed to start screen capture stream: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/gpui_macos/src/screen_capture.rs","lineNumber":112,"sourceCode":"                output_protocol,\n                SCStreamOutputType::Screen,\n                None,\n            ) {\n                _ = sender.send(Err(anyhow!(\n                    \"failed to add stream output: {}\",\n                    error.localizedDescription()\n                )));\n\n                return receiver;\n            }\n\n            let state = Rc::new(RefCell::new(Some((sender, stream.clone(), output))));\n            let handler = RcBlock::new(move |error: *mut NSError| {\n                let Some((sender, stream, output)) = state.borrow_mut().take() else {\n                    return;\n                };\n                let result = if let Some(error) = error.as_ref() {\n                    Err(anyhow!(\n                        \"failed to start screen capture stream: {}\",\n                        error.localizedDescription()\n                    ))\n                } else {\n                    Ok(Box::new(MacScreenCaptureStream {\n                        meta: metadata.clone(),\n                        sc_stream: stream,\n                        sc_stream_output: output,\n                    }) as Box<dyn ScreenCaptureStream>)\n                };\n\n                _ = sender.send(result);\n            });\n            stream.startCaptureWithCompletionHandler(Some(&handler));\n        }\n\n        receiver\n    }","sourceCodeStart":94,"sourceCodeEnd":130,"githubUrl":"https://github.com/zed-industries/zed/blob/916fc2b8cb3a815cbef4a3b40e13081be72036b6/crates/gpui_macos/src/screen_capture.rs#L94-L130","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Grant the app Screen Recording permission in System Settings > Privacy & Security > Screen Recording, then restart the app.","Re-enumerate displays/windows (SCGetShareableContent) immediately before starting the stream and capture a still-valid ID.","Log the underlying NSError description (it is embedded in the message) to identify the exact ScreenCaptureKit failure.","Retry stream creation once, as ScreenCaptureKit occasionally fails transiently right after permission is granted."],"exampleFix":"// before\nlet stream = ScreenCaptureStream::new(output, sender);\n// after\n// check permission / re-enumerate and surface the underlying description\nmatch ScreenCaptureStream::new(output, sender) {\n    Ok(stream) => use_stream(stream),\n    Err(e) => prompt_screen_recording_permission(&format!(\"{e:#}\")),\n}","handlingStrategy":"try-catch","validationCode":"fn can_request_screen_capture() -> bool {\n    // macOS 12.3+ required for ScreenCaptureKit\n    (cfg!(target_os = \"macos\") && os_version_at_least(12, 3)) || !cfg!(target_os = \"macos\")\n}","typeGuard":null,"tryCatchPattern":"match ScreenCaptureStream::new(output, sender) {\n    Ok(stream) => stream,\n    Err(e) if format!(\"{e:#}\").contains(\"not permitted\") => prompt_for_screen_recording_permission(),\n    Err(e) => return Err(anyhow!(\"screen capture unavailable: {e:#}\")),\n};","preventionTips":["Check screen recording permission (CGPreflightScreenCaptureAccess) before starting a stream.","Re-enumerate displays/windows right before capture and handle the target disappearing.","Surface the embedded NSError description to the user rather than only the wrapper message."],"tags":["macos","screen-capture","screencapturekit","permission"],"backgroundTag":"screen-capture-start-failed","analyzedSha":"916fc2b8cb3a815cbef4a3b40e13081be72036b6","analyzedAt":"2026-09-19T19:09:50.599Z","contentChangedAt":"2026-09-19T19:09:50.599Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}