screen sharing not working: support checklist

TL;DR

Screen sharing fails in three places: the browser never got permission (the OS-level screen recording permission, especially on Mac), the user shared the wrong target (a window instead of the screen, or vice versa), or corporate policy blocks it. Check permissions first: on Mac the screen-recording permission needs the browser restarted after granting. Then confirm the share target. Then ask about VPNs and managed devices.

The query

screen sharing not working: support checklist

Use this when

• Users report black screens when sharing
• Screen share freezes or never starts
• Permission errors on share
• Writing video-call troubleshooting docs

Not for

• Building screen-sharing features
• WebRTC infrastructure debugging
• Firewall administration
• Audio issues (separate checklist)

Steps

1. Check OS-level screen recording permission

On Mac, the browser needs Screen Recording permission in system settings, and the browser must restart after it is granted. On Windows, check the app permissions. This is the top cause of black screens.

Expected output: permission granted and browser restarted.

2. Confirm the share target

Entire screen, application window, or browser tab: the user must pick the right one, and the thing they want to show must be on the picked target. "Black screen" often means they shared a minimized window.

Expected output: correct target selected and visible.

3. Restart the share cleanly

Stop sharing entirely, wait a few seconds, and start again. Do not toggle rapidly; the capture pipeline needs a clean restart. If the browser tab froze, reload the call.

Expected output: a fresh share session.

4. Check for corporate blocks

Managed devices, VPNs, and DLP software can block screen capture by policy. Ask: work device or personal, VPN on or off. If policy blocks it, no troubleshooting will help; say so and offer alternatives.

Expected output: policy block confirmed or ruled out.

Template: the checklist reply

Black or frozen screen sharing is usually a permission issue, [Name]. Let us walk through it:

1. Mac: open System Settings, go to Privacy and Security, then Screen Recording, and make sure [browser] is enabled. Then fully quit and reopen the browser. This restart step is required.
   Windows: check that [browser] has permission to record the screen.
2. When you click Share, pick the right target: "Entire screen" to show everything, or the specific window. Make sure that window is not minimized.
3. Stop the share, wait a few seconds, and start it fresh.
4. Work laptop or VPN? Some company policies block screen sharing. If the above does not help, that may be it.

Tell me which step you are on and what you see.

Variant phrasings

screen share black screen

Steps 1 and 2. Permissions, then the share target.

cannot share screen on mac

Step 1. The screen-recording permission plus browser restart.

screen sharing frozen

Step 3. Clean restart of the share.

Why it works

Screen sharing crosses OS permissions, browser capture, and network, and each layer fails differently. The permission check catches the most common case (Mac), the target check catches the most embarrassing case (minimized window), and the policy check stops you from debugging something unfixable.

Edge cases

• Sharing DRM-protected content (streaming video): the OS blacks it out by design. Not fixable; explain it.
• Multiple monitors: the user may be sharing the wrong display. Ask which monitor.
• Wayland on Linux: screen sharing needs portal support; some browsers need flags. Know your supported configs.
• It works in one browser but not another: permissions are per-browser. Grant per browser.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_xFWY6zJWr5atK3Sccr3hOQ