`screen.grab()` doesn't work on macOS Tahoe

[domdomegg]

Version

nut-js 4.2.6, libnut-darwin 2.7.5

Short overview

screen.grab() fails with "Failed to capture screen" on macOS 26 (Tahoe). I think this may be related to nut-tree/libnut-core#187, and be because Apple has now fully removed CGDisplayCreateImageForRect from the CoreGraphics dylib in macOS 26, so the call from screengrab.m there fails at runtime.

Issue occurs on

• Virtual machine
• Docker container
• Dev/Host system

node version: v25.6.1

OS type and version: macOS 26.1 (Tahoe), build 25B78, arm64

Detailed error description

screengrab.m calls CGDisplayCreateImageForRect (line 22). This API was deprecated in macOS 15 (Sequoia) in favour of ScreenCaptureKit, but the symbol still existed at runtime so everything kept working. In macOS 26 (Tahoe), Apple fully removed it:

$ nm -g /System/Library/Frameworks/CoreGraphics.framework/CoreGraphics | grep CGDisplayCreateImageForRect
(no output — symbol gone)

Similarly, CGWindowListCreateImage (used elsewhere) is also gone:

$ swift -e 'import CoreGraphics; let _ = CGWindowListCreateImage(.infinite, .optionOnScreenOnly, kCGNullWindowID, .bestResolution)'
error: 'CGWindowListCreateImage' is unavailable in macOS: Please use ScreenCaptureKit instead.
note: 'CGWindowListCreateImage' was obsoleted in macOS 15.0

Other screen capture methods still work — the screencapture CLI produces valid screenshots, and accessibility/mouse APIs (getMousePos, moveMouse, etc.) are unaffected. Only captureScreen fails.

Full code sample to reproduce

const { screen } = require("@nut-tree/nut-js");

screen.grab().then((img) => {
  console.log("Success:", img.width, "x", img.height);
}).catch((err) => {
  console.error("Error:", err.message);
});

Output:

Error: Error: Failed to capture screen
    at libnut.<computed> (permissionCheck.js:82:58)
    at libnut.<computed> [as captureScreen] (permissionCheck.js:87:60)
    at module.exports.screen.capture (index.js:40:20)
    ...

Note: getAuthStatus("screen") returns "authorized" — permissions are granted, the underlying API just no longer exists.

Additional content

The fix likely needs to happen in libnut-core/src/macos/screengrab.m, by replacing CGDisplayCreateImageForRect with ScreenCaptureKit (SCScreenshotManager.captureImage) on macOS 15+

[s1hofmann]

Hi @domdomegg

this issue has already been addressed in a non-public release, see https://nutjs.dev/changelog/libnut

[domdomegg]

Nice - is there any ETA on when the code changes might land in GitHub? From your post I was under the impression the built packages would be private but the repo sources would be updated for others to build and host them themselves. But I don't know if this has changed etc./I've missed something (apologies if so!)

[s1hofmann]

It’s planned after major releases. So now that v5 is out, I’ll work in this after I finished my current project.

[m13v]

We hit this exact same breakage in our macOS screen capture pipeline. Apple fully removed CGDisplayCreateImageForRect and CGWindowListCreateImage in macOS 26 - there is no workaround, you have to migrate to ScreenCaptureKit.

The migration path we took: use SCShareableContent.excludingDesktopWindows(false, onScreenWindowsOnly: true) to enumerate displays, create an SCContentFilter for the target display, configure SCStreamConfiguration with the display dimensions and pixel format, then call SCScreenshotManager.captureImage(contentFilter:configuration:). For the equivalent of CGDisplayCreateImageForRect with a sub-region, you capture the full display and crop the CGImage after.

One gotcha - ScreenCaptureKit is async and requires the main runloop to be pumping. If your native addon calls from a worker thread, you need to dispatch to the main queue. Also, the first call to SCShareableContent can take 200-300ms (it talks to the WindowServer), so caching the shareable content and refreshing it on display configuration changes is worth doing.

For the permission check, replace CGPreflightScreenCaptureAccess() with SCShareableContent.current and catch the authorization error - the old CoreGraphics permission APIs are also deprecated.

[m13v]

For reference, here is our ScreenCaptureKit implementation that replaced the deprecated CGDisplay APIs: https://github.com/m13v/fazm/blob/main/Desktop/Sources/FloatingControlBar/ScreenCaptureManager.swift

And our MCP server that drives macOS screen control (accessibility + screen capture combined): https://github.com/mediar-ai/mcp-server-macos-use/blob/main/Sources/MCPServer/main.swift