---
title: Troubleshooting remote desktop connections to Mac mini servers
description: This page provides solutions for when you cannot establish a remote desktop connection to your Mac mini.
tags: remote vnc connection apple-silicon error
dates:
  validation: 2025-08-05
  posted: 2023-04-07
---
import Requirements from '@macros/iam/requirements.mdx'


<Requirements />
- A Scaleway account logged into the [console](https://console.scaleway.com)
- [Owner](/iam/concepts/#owner) status or [IAM permissions](/iam/concepts/#permission) allowing you to perform actions in the intended Organization
- An [SSH key](/organizations-and-projects/how-to/create-ssh-key/)
- A [Mac mini](/apple-silicon/how-to/create-mac-mini/)

## 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:
```bash
ping -c 5 <server_ip>
```
If `ping` fails:
- Try [rebooting the server](/apple-silicon/how-to/reboot-mac-mini/).
- If the server was forced to shut down, wait 24 hours for automatic restart.

<Message type="important">
  [Enabling FileVault](/apple-silicon/faq/#can-i-enable-filevault-on-a-hosted-mac-mini) 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.
</Message>

#### Verify the VNC connection
Run the following command:
```bash
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](/apple-silicon/how-to/reboot-mac-mini/).
- Restart screen sharing via SSH (see below).

#### Verify the SSH server response
Run the command:
```bash
nc -zv <server_ip> 22
```
If the connection fails, [reboot the server](/apple-silicon/how-to/reboot-mac-mini/).

#### Check for connection blocking
If VNC connection attempts fail repeatedly, your connection may be blocked. [Rebooting](/apple-silicon/how-to/reboot-mac-mini/) 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](/apple-silicon/how-to/access-remote-desktop-mac-mini/#comparison-matrix-of-remote-desktop-clients) for recommendations.

#### Reinstall the Mac mini
If all else fails, [reinstall macOS](/apple-silicon/how-to/reinstall-mac-mini/) via the Scaleway console.
<Message type="important">
  Reinstalling your Mac mini will delete all data on its disk. Ensure you have a backup of your data before launching any reinstallation.
</Message>

## 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:
    ```bash
    sudo nano /etc/pf.conf
    ```
2. Add the following lines to the file and save it:
    ```bash
    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:
    ```bash
    sudo pfctl -f /etc/pf.conf
    ```

### Restarting screen sharing via SSH
1. Connect via SSH:
    ```bash
    ssh your_mac_mini_username@<your_mac_mini_ip>
    ```
2. Restart screen sharing:
    ```bash
    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).

<Message type="important">
  `WindowServer` ignores `SIGTERM`, so a plain `killall WindowServer` has no effect. You must send `SIGKILL` (the `-9` flag).
</Message>

1. Connect via SSH:
    ```bash
    ssh your_mac_mini_username@<your_mac_mini_ip>
    ```
2. Force a restart of the graphics session:
    ```bash
    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.

<Message type="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.
</Message>

## Further troubleshooting
If the issue persists, contact [Scaleway's support](https://console.scaleway.com/support) for assistance.