Skip to navigationSkip to main contentSkip to footerScaleway Docs HomepageAsk our AI
Ask our AI
Log inSign up

Troubleshooting remote desktop connections to Mac mini servers

Before you start

To complete the actions presented below, you must have:

Problem

You are unable to establish a remote desktop (VNC) connection to your Scaleway Mac mini.

Symptoms

  • VNC client fails to connect to the Mac mini.
  • Authentication errors occur during connection attempts.
  • Connection times out or is refused.
  • Mac mini appears unreachable.
  • The VNC connection succeeds and authentication is accepted, but the screen is completely black.

Possible causes

  • The Mac mini is powered off or unresponsive.
  • The VNC port assigned during system setup is incorrect.
  • The SSH server is unresponsive.
  • Your connection is blocked due to failed attempts.
  • Incorrect credentials are being used.
  • Remote connection client compatibility issues.
  • The WindowServer graphics process is stuck and serving a black frame (typically after a very long uptime).

Solution

Verify the server status

Run the following command in a terminal:

ping -c 5 <server_ip>

If ping fails:

  • Try rebooting the server.
  • If the server was forced to shut down, wait 24 hours for automatic restart.
Important

Enabling FileVault on a Mac encrypts the disk, preventing remote connections, such as Remote Desktop or SSH, until the FileVault security key or user password is entered. This requires physical access to the machine, making remote management unavailable until unlocked.

Verify the VNC connection

Run the following command:

nc -zv <server_ip> <vnc_port>

If the connection fails:

  • Verify the correct VNC port in the Overview section of your Scaleway console.
  • Reboot the server.
  • Restart screen sharing via SSH (see below).

Verify the SSH server response

Run the command:

nc -zv <server_ip> 22

If the connection fails, reboot the server.

Check for connection blocking

If VNC connection attempts fail repeatedly, your connection may be blocked. Rebooting clears the fail2ban table.

Verify your connection credentials

  • VNC: Ensure correct username and password.
  • SSH: Ensure your SSH key was provided before installation.

Verify remote access client compatibility

Use a compatible VNC client. See this guide for recommendations.

Reinstall the Mac mini

If all else fails, reinstall macOS via the Scaleway console.

Important

Reinstalling your Mac mini will delete all data on its disk. Ensure you have a backup of your data before launching any reinstallation.

Advanced configuration and security

Enabling and configuring Packet Filter (pf)

  1. Open the pf configuration file in a text editor to restrict access to screen sharing: 
    sudo nano /etc/pf.conf
  2. Add the following lines to the file and save it: 
    block in on en0 proto tcp from any to any port 5900
pass in on en0 proto tcp from <static IP> to any port 5900
  3. Apply the configuration: 
    sudo pfctl -f /etc/pf.conf

Restarting screen sharing via SSH

  1. Connect via SSH: 
    ssh your_mac_mini_username@<your_mac_mini_ip>
  2. Restart screen sharing: 
    sudo killall screensharingd

Fixing a black screen by restarting WindowServer via SSH

If the VNC connection succeeds and your credentials are accepted, but the screen remains completely black, the WindowServer graphics process has likely frozen and is serving a black frame to the screen-capture pipeline. This can happen after a very long uptime.

Restarting screensharingd does not fix this, because it is respawned on demand for each new connection (a fresh, still-black session starts on every attempt).

Important

WindowServer ignores SIGTERM, so a plain killall WindowServer has no effect. You must send SIGKILL (the -9 flag).

  1. Connect via SSH: 
    ssh your_mac_mini_username@<your_mac_mini_ip>
  2. Force a restart of the graphics session: 
    sudo killall -9 WindowServer

This restarts the graphics session (data on the disk is not affected) and returns the Mac to the login screen. Reconnect via VNC: the screen should now display correctly, and you can log in.

Note

A software reboot (the console Reboot button or sudo reboot) can be silently blocked by an application's unsaved-changes dialog that is invisible on the black screen. Restarting WindowServer directly avoids this. SSH remains available throughout, so there is no risk of lock-out.

Further troubleshooting

If the issue persists, contact Scaleway's support for assistance.

Still need help?

Create a support ticket
No Results