macOS server troubleshooting: access, sleep, keychain and Xcode

A remote Mac is a normal Mac with a long cable. When something goes wrong, the cause is usually one of a handful of things. Find your symptom below.

Before you start

• Know your Mac's connection methods: HyperDC Web Console for every HyperDC Mac; VMRC for Intel macOS VPS and VDS; Apple Remote Desktop and HyperDC Remote Connect for Apple Silicon macOS VPS and Mac dedicated servers. See first steps on a macOS server.
• Check Support › Network Status in the client area for maintenance or incidents at your location.

I cannot reach the desktop

Try the HyperDC Web Console first. Open your service in the client area and start the Web Console.

• The Web Console shows the desktop: the Mac runs. The problem is your other method or the network between you and the Mac. For Apple Remote Desktop, check that ports 3283 and 5900 are not blocked on your side and that Remote Management is on; see Apple Remote Desktop.
• The Web Console shows the login window: the Mac restarted. Sign in; apps that need a session, such as Docker Desktop, start again after sign-in.
• The Web Console shows a black screen: the display is asleep. Move the mouse or press a key in the console window. If it stays black, disconnect and connect again.
• The Web Console does not connect either: open a ticket with your service name and the time the problem started.

The Mac goes to sleep

Builds stop and connections drop when the Mac sleeps. In Terminal:

pmset -g
sudo pmset -a sleep 0

On Mac dedicated servers, also check System Settings › Energy; see set up a Mac dedicated server.

codesign fails over SSH or in CI

Symptom: codesign or xcodebuild archive works in the desktop but fails over SSH or in a CI job with errSecInternalComponent.

Cause: the login keychain is locked in that session. macOS unlocks it at a desktop sign-in, not for SSH.

Fix: unlock the keychain in the same shell session or command chain as the signing step:

security unlock-keychain ~/Library/Keychains/login.keychain-db && xcodebuild -scheme MyApp archive

In CI, keep the keychain password in the CI system's secret store and pass it to security unlock-keychain -p at runtime; never write it into scripts. If signing still fails, look for duplicate or expired identities:

security find-identity -v -p codesigning

A simulator runtime is missing

Symptom: Xcode or xcodebuild test reports that no matching destination or simulator runtime is available.

Fix: list what is installed, then download the platform with Xcode's command-line tool:

xcrun simctl list runtimes
xcodebuild -downloadPlatform iOS

Runtimes take several gigabytes each; check df -h / first.

Xcode will not install or open

The macOS version is too old for that Xcode release. Check Apple's Xcode system requirements, then update macOS or choose an Xcode that supports your version; see macOS VPS and VDS for how Xcode releases and macOS versions relate.

The disk is full

df -h /
xcrun simctl delete unavailable
du -sh ~/Library/Developer/Xcode/DerivedData

Delete old DerivedData folders, archives you have uploaded and Xcode versions you no longer need. You can add disk space in the order form or move to a larger plan.

SSH: Connection refused

Remote Login is off. Turn it on in System Settings › General › Sharing through the Web Console, then connect again.

macOS updates fail or stop halfway

Check free space and the update list:

softwareupdate --list

Install with sudo softwareupdate --install --all --restart when no jobs are running. On a virtual Mac, ask us before a major macOS upgrade, so we can confirm the new version is supported for your plan.

Next steps

• Prepare a build machine: macOS server for iOS CI.
• Mac dedicated servers: set up a Mac dedicated server.