[Bug]: macOS — takes end with SCStreamErrorDomain -3821 "Stream was stopped by the system" when the disk is low on free space

Start with electron/recording/nativeMacCaptureStop.ts and electron/native/screencapturekit/Sources/OpenScreenScreenCaptureKitHelper/ScreenCaptureRecorder.swift, which the report identifies as passing the macOS stream error through to the user. Check how the app reads free space on the recordings volume and handles SCStreamErrorDomain code -3821; the report proposes a clearer message and a low-space warning, with stream recovery as an option. Done means the reported failure gives users useful guidance, and any warning or recovery behavior is covered by relevant tests.

Search existing issues

• I have searched the existing issues

Describe the bug

TLDR: if you're low on space on your machine, make the error a bit more obvious regarding what's happening. 😄

On macOS 26, five takes in one 15-minute session ended early with:

Recording ended early (Error Domain=com.apple.ScreenCaptureKit.SCStreamErrorDomain Code=-3821 "Stream was stopped by the system" UserInfo={NSLocalizedDescription=Stream was stopped by the system}). The part recorded until then was saved.

From the user's side this looks random: the stops came 1 s, 37 s, 95 s, 205 s and 289 s into a take. The unified log shows the cause. The data volume had less free space than macOS wants to keep (the CacheDelete purge goal in the log is ~15 GB on this 500 GB disk). While it is below that, the CacheDelete daemon (deleted) runs a purge every few minutes and asks replayd to free space at high urgency. replayd responds by calling stopAllStreamsWithError:, which ends every active ScreenCaptureKit stream, OpenScreen's included.

The sequence is the same for all five stops. Here is one of them:

14:25:03.797 deleted   Purge: goal 14817637171 freespace 9721704448
14:25:11.465 replayd   -[RPRecordingManager purge:urgency:]:263 cacheDeleteUrgencyHigh
14:25:11.465 replayd   -[RPClient handleMemoryWarningForCurrentActiveSession]:1085 We don't have a current active session.
14:25:11.465 replayd   -[RPClient stopAllStreamsWithError:]:1521
14:25:11.590 replayd   -[RPClient stopAllStreamsWithError:]_block_invoke:1532 Stopped stream=<private>
14:25:11.591 openscreen-screencapturekit-helper  -[SCStreamManager stream:didStopWithError:]:125 didStopWithError=Error Domain=com.apple.ScreenCaptureKit.SCStreamErrorDomain Code=-3821

The takes I stopped myself in the same session ended normally. replayd logged stopAllStreamsWithError: 298 times that day, so on a nearly full disk any take longer than a few minutes is likely to be cut.

Recording makes the problem worse as it goes. With the webcam at 1440p, one 289 s take wrote an 868 MB WebM plus a 380 MB MP4, so every take pushes free space further below the threshold.

The stop itself comes from macOS. replayd kills third-party streams even though it has no ReplayKit session of its own to purge, so OpenScreen can't prevent it. The app currently passes the raw NSError through: stream(_:didStopWithError:) in ScreenCaptureRecorder.swift emits capture-stopped-with-error, and nativeMacCaptureStop.ts wraps it in "Recording ended early (…)". This is unchanged on current main, so 2.2.x should behave the same as 2.1.2.

Expected behavior

OpenScreen can't stop macOS from doing this, but it could make the failure understandable and less costly:

1. Name the likely cause. When a take ends with -3821 and the recordings volume is low on space, say so. For example: "macOS stopped the recording because the disk is almost full (8.5 GB free). macOS interrupts screen recordings while free space is low. Free up space and record again."
2. Warn before recording. Show a warning in the HUD when the recordings volume is below ~15 GB free (or below whatever threshold deleted uses).
3. Optionally, recover. On -3821, restart the stream and continue the same take instead of ending it. Each time, a new take on the same display (started by hand 20–80 s later) worked. Purges come in bursts, though, with another stopAllStreamsWithError: often 5–15 s after the first, so an automatic restart would need to wait or retry.

To Reproduce

1. Reduce free space on the data volume to below ~15 GB.
2. Start a screen recording with OpenScreen (display capture through Apple's picker; webcam, microphone and system audio were on).
3. The take ends with the -3821 toast within a few minutes, at the next CacheDelete purge.

I matched this against the logs of an actual session. I didn't reproduce it by filling the disk on purpose.

To confirm the cause on an affected Mac:

/usr/bin/log show --last 1h --style compact --predicate '(process == "deleted" AND eventMessage CONTAINS "Purge: goal") OR (process == "replayd" AND eventMessage CONTAINS "stopAllStreamsWithError")'

OS

macOS

OS Version

macOS 26.0.1 (25A362)

Device Type

Desktop (Mac Studio, M4 Max)

Additional context

• OpenScreen 2.1.2 (com.etiennelescot.openscreen)
• The partial takes were saved correctly, with matching screen and webcam durations, so stopping and saving the take works. The only problems are the message and the interruption itself.
• Related but different: #621, where the writer died and ScreenCaptureKit kept running. Here ScreenCaptureKit itself is stopped by the OS.