Enhance VNC troubleshooting for black screen issues#6673
Open
youssefbenhammed wants to merge 1 commit into
Open
Enhance VNC troubleshooting for black screen issues#6673youssefbenhammed wants to merge 1 commit into
youssefbenhammed wants to merge 1 commit into
Conversation
Added troubleshooting steps for VNC black screen issue and clarified the importance of restarting WindowServer via SSH.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
This adds a troubleshooting case that is currently not covered: the VNC connection succeeds and authenticates, but the remote screen is completely black.
In this situation the
WindowServergraphics process has frozen (typically after a very long uptime) and serves a black frame to the screen-capture pipeline. The existing Restarting screen sharing via SSH step (killall screensharingd) does not help, becausescreensharingdis respawned on demand for each new connection.The fix is to force a restart of
WindowServerover SSH:WindowServerignoresSIGTERM, so-9(SIGKILL) is required. A software reboot (the console Reboot button orsudo reboot) can be silently blocked by an invisible unsaved-changes dialog on the black screen, so restartingWindowServerdirectly is more reliable. SSH stays available throughout, so there is no lock-out risk.Verified on a live Scaleway Mac mini (M2, macOS 15.2): VNC connected and authenticated but showed a black screen after a very long uptime;
sudo killall -9 WindowServerrestored the display immediately. Matching entries were also added to the Symptoms and Possible causes lists.Your checklist for this pull request