Start with the symptom

Break connection and build issues into verifiable steps

You do not need to read the entire guide first. Start with connection, environment, automation, network, or storage, then verify the address, permissions, tool versions, and logs in order. Each step includes an expected result so you can decide whether to continue troubleshooting or submit a ticket.

View troubleshooting paths Submit a console ticket
6 categories Documentation sections
2 options Remote connection methods
5 paths Symptom decision paths
Documentation index

Choose the task you are performing

Each entry links to specific checks on this page. Change one variable at a time and record the commands, versions, and results before and after the change.

First connection Prepare credentials, verify the host fingerprint, replace keys, and end the session correctly. CONNECT Development environment Check the Xcode path, build targets, dependency resolution, and log archive location. TOOLCHAIN Automated builds Register a self-hosted runner and plan its labels, concurrency, and working directory. RUNNER Network access Use verbose logs to distinguish a wrong address, unreachable port, timeout, and authentication failure. NETWORK Storage management Locate space used by DerivedData, caches, archives, and working directories. STORAGE Troubleshooting Enter the decision tree by symptom and get the next verifiable action. RESOLVE
Troubleshooting principle: Do not upgrade Xcode, replace dependencies, switch networks, and change signing settings at the same time. Change one thing at a time so the result reveals the real cause.
Remote connections

SSH and VNC follow different verification paths

SSH is suited to command-line work, automation, and file transfer; VNC is suited to tasks requiring the macOS graphical interface. For both, verify the node address first, then verify the credentials.

Command-line path

SSH connection checks

  1. 01
    Prepare connection details

    Verify the host address, port, username, and temporary access method from the order delivery details. Do not copy an address from old terminal history if it may have changed.

  2. 02
    Perform the first verification

    Run a verbose connection from a trusted network first, and continue only after verifying the host fingerprint. Stop immediately if the fingerprint does not match the delivery details.

  3. 03
    Replace temporary credentials

    Add your SSH public key to the authorized file. Confirm that a new session works before removing temporary access entries you no longer use.

  4. 04
    End the session correctly

    Stop foreground tasks first and confirm that logs have been written, then use exit to exit. Do not close a terminal that is still running a release task.

  5. 05
    Check access issues

    For timeouts, check the network and port first; for connection refusals, check the address and service status; for authentication failures, check the username, key permissions, and authorized file.

Graphical interface path

VNC connection checks

  1. 01
    Prepare the client and address

    Use a trusted VNC client and enter the node address and port from the delivery details. Disable unnecessary credential-saving features in the client before connecting.

  2. 02
    Complete the first screen verification

    Confirm that the expected macOS graphical interface is displayed and verify the region and device configuration. If the screen is abnormal, do not immediately import code or certificates.

  3. 03
    Update access credentials

    Replace the temporary password and reconnect to verify that the new credentials work. Do not store complete credentials in team chats or build scripts.

  4. 04
    Exit idle sessions

    Save your work, close sensitive windows, and exit the session. In collaborative work, record the current user and any running graphical tasks.

  5. 05
    Locate display issues

    For a black screen, reconnect and check the session status; for lag, lower the display quality; if the connection cannot be established, return to checking the address, port, and local network.

Connection diagnostics

Read SSH verbose logs instead of retrying blindly

Verbose mode shows whether the connection stops at the network, fingerprint, or authentication stage. The address below is for illustration only; use the order delivery details for the actual connection information.

support-check · ssh diagnostic 
$ ssh -v -p 22 build@203.0.113.24
OpenSSH: reading configuration data
debug1: Connecting to 203.0.113.24 port 22
debug1: Connection established
debug1: identity file ~/.ssh/id_ed25519 type 3

The authenticity of host cannot be established.
ED25519 key fingerprint is SHA256:verify-with-delivery-record
Continue connecting only after fingerprint verification.

debug1: Server host key accepted
debug1: Offering public key: ~/.ssh/id_ed25519
debug1: Authentication succeeded (publickey)
Connected to the dedicated physical Mac node

$ sw_vers
ProductName: macOS

$ exit
Connection closed.
TIMEOUT

Stuck at Connecting for a long time

Switch to a network known to work, then verify the address and port. If multiple networks time out, record the time, local egress environment, and complete logs.

FINGERPRINT

Host fingerprint does not match the record

Stop connecting. Do not delete the local known-host record and retry. First verify the order node and delivery details, then confirm the reason for the change through a support ticket.

AUTH

Network works but authentication fails

Check the username, private-key path, file permissions, and whether the public key was fully added to the authorized file. When submitting logs, hide key contents and retain only authentication-stage information.

Development toolchain

Fix the Xcode selection before investigating project-level errors

The most common sources of build-environment drift are inconsistent command-line tool paths, target names, dependency states, and signing variables. Verify the machine layer before moving to the project layer.

XCODE

Confirm the command-line tools selection

Run xcode-select -p to view the current path, then use xcodebuild -version to verify the version. After switching versions, reopen the terminal so subsequent tasks use a consistent environment.

Expected: path and version match
TARGET

List the available targets

First run xcodebuild -listand confirm the workspace, project, scheme, and configuration names before putting the exact names into automation commands.

Expected: targets can be enumerated
SIGNING

Separate signing variables from project configuration

Check that the variables required for the build exist in the current session without writing sensitive values to the repository. Output only whether each variable exists; never echo its full value in logs.

Expected: variables exist without leaking secrets
LOGS

Archive complete build records

For every task, retain the command, start time, exit code, build log, and artifact path. On failure, also retain the context around the first error rather than copying only the final summary.

Expected: failures are reproducible
Automated builds

Make your self-hosted runner identifiable, isolated, and removable

Runner integration is not just about making the first task succeed. Subsequent tasks must know which node and directory to use, and registration must be cleaned up when the runner is retired.

  1. 01

    Verify the execution identity before registration

    Create a dedicated runtime identity and working directory. Confirm that it can read the repository and write to the build directory without default administrative permissions unrelated to builds.

    Validation: a manual task completes under the same identity
  2. 02

    Use labels to describe real capabilities

    Labels should describe the region, chip family, major Xcode version, and purpose. Avoid labels such as “latest” or “fastest” that become inaccurate over time.

    Validation: scheduling conditions uniquely match the target node
  3. 03

    Isolate working directories

    Use separate subdirectories for different repositories or pipelines and manage caches separately. Clean temporary files after each task, while retaining clearly sourced caches that are still needed.

    Validation: the two tasks do not overwrite each other’s artifacts
  4. 04

    Limit concurrency and contention

    Start with one task, observe CPU, memory, disk, and build time, then decide whether to increase concurrency. Graphical tasks and heavy builds should not run simultaneously without a record.

    Validation: swap usage does not keep growing during peaks
  5. 05

    Fully unregister when retiring

    Stop accepting new tasks first, wait for the current task to finish, then unregister the runner from the automation platform and remove the registration token and unneeded working directory.

    Validation: old labels no longer accept tasks
Do not assign the same working directory to multiple concurrent tasks. Dependency caches, DerivedData, archives, and temporary signing files can overwrite one another and cause seemingly random build failures.
Terminology

Standardize these eight terms first

Using the same terminology in tickets and team documentation reduces confusion between networks, devices, sessions, and build tools.

Physical node
The hardware device actually running macOS. A BookaMac order corresponds to a physical Mac mini, not an abstract shared compute instance.
Dedicated
During the rental period, the device is assigned to one customer and its physical machine is not shared with other customers’ workloads.
Cloud Mac
A Mac located on a remote node and accessible over a network. The term describes its location and access method, not a virtual machine.
VNC
A connection method for viewing and operating the macOS graphical interface remotely, suited to tasks requiring windows, display, and interaction.
SSH
An encrypted command-line connection method for running scripts, transferring files, managing build tasks, and collecting diagnostic logs.
self-hosted runner
An automation task executor registered and managed by your team, with tasks running on a designated dedicated physical Mac node.
Build cache
Intermediate data retained to reduce repeated downloads and compilation. Caches can speed up tasks but may cause environment drift when versions change.
Provisioning profile
One of the signing configuration materials used by release and testing workflows. Manage it according to project permissions and remove it when handing over or leaving an environment.
Symptom decision tree

Move from what you see to the next check

Expand the symptom that best matches your situation. Complete one checkpoint before moving to the next; do not skip steps without recording results.

Cannot connect to the node: what should I check first?
  1. Confirm the address:Copy the host address, port, and username again from the current order delivery details.
  2. Distinguish timeout from refusal:A timeout usually points first to the local network or link; an immediate refusal points to the address, port, or connection method.
  3. Open verbose logs:Use ssh -v to determine whether a network connection was established, whether fingerprint verification passed, and where authentication stopped.
  4. Retest on another trusted network:If the result changes, record both network environments instead of reporting only “it connects occasionally.”
  5. Escalate to support:If multiple networks fail, submit a ticket with the order ID, region, time, and redacted verbose logs.
Build failed: is it Xcode, the project, or a dependency?
  1. Pin the versions:Record the output of xcode-select -p and xcodebuild -version .
  2. List the targets:Confirm that the scheme, configuration, workspace, or project name actually exists.
  3. Find the first error:Locate the first clear error in the logs instead of working backward from the final failure summary.
  4. Verify dependencies:Without modifying project files, resolve dependencies again from the lockfile and compare the results.
  5. Narrow the scope:Build the smallest target separately to determine whether the failure belongs to the environment, project configuration, or a specific module.
Disk full: which directories should I check first?
  1. Confirm overall usage:Use df -h to check volume-level space, not just one project directory.
  2. Locate large directories:Check DerivedData, archives, simulator data, dependency caches, and the runner working directory.
  3. Separate caches from artifacts:Caches can be rebuilt; archive deliverables and diagnostic logs before cleaning them up.
  4. Stop active tasks:Before cleaning, confirm that no build is writing to the target directory to avoid corrupted intermediate state.
  5. Review what is growing:Observe the space added by the next task after cleanup to find the directory that keeps growing.
Certificate or provisioning-profile issue: how can I avoid reinstalling blindly?
  1. Record the exact error:Distinguish not found, expired, insufficient permissions, and configuration mismatch.
  2. Verify the build target:Confirm that the current scheme, configuration, and signing settings belong to the expected project.
  3. Check Keychain permissions:Verify that the build identity can access the required materials without expanding unrelated permissions.
  4. Check the provisioning profile:Confirm that it matches the current task and avoid retaining multiple hard-to-distinguish old versions.
  5. Protect sensitive materials:Submit only the error, names, and required metadata in a ticket; never send private keys or complete credentials.
Connection or build speed varies: how do I locate the issue?
  1. Provide a time range:Record the start, end, and whether the issue is ongoing. Do not describe it only as “slow lately.”
  2. Measure separately:Observe the remote display, file transfer, dependency downloads, and local build separately instead of reducing them to one speed conclusion.
  3. Check concurrent tasks:See whether other builds, indexing, transcoding, or model tasks are consuming resources at the same time.
  4. Compare networks:Repeat the same action on different trusted networks to distinguish the local link from pressure on remote tasks.
  5. Keep a sample:Submit the region, time, command duration, and redacted logs so the issue can be checked again under the same conditions.
Support escalation

What should a troubleshooting ticket contain?

Organize the facts first, then submit them through the console. Complete context usually helps locate the issue faster than multiple follow-up screenshots.

01

Order ID

Provide only the required order identifier. Do not send payment credentials or unrelated information.

02

Node region

Specify Singapore, Japan (Tokyo), South Korea (Seoul), or Hong Kong, along with the connection method used.

03

Time of occurrence

Include the time zone, when it first appeared, how long it lasted, and whether it can be reproduced consistently.

04

Redacted logs

Keep commands, exit codes, and error context while hiding tokens, passwords, private keys, and complete credentials.

Reproduce from the documentation, then bring the evidence to your ticket

Use the console to view existing orders and submit technical tickets. If you are still choosing a configuration, compare the specifications and suitable workflows of two dedicated physical Mac mini plans.

Go to the console Compare configurations