Start with the symptoms
Enter an error message, tool name, or connection method. Instead of generic explanations, this page lists device status checks, log locations, verification commands, and the information needed to escalate to human support—in order.
Quick routing
Choose the closest symptom, then follow the checks in order. Do not reinstall Xcode, dependencies, or the Runner before confirming network and disk status.
First connection
Connection issues usually occur at one layer: status, credentials, network, or client configuration. Following the checks in order helps prevent mistaking a network issue for a device issue.
Sign in to the console first to check whether the instance is available, then verify the device name and node linked to the order. If the console shows the device as available but both connection methods fail, continue with network checks; do not change system settings first.
Distinguish the system username, initial password, and SSH key. When copying credentials, check for leading or trailing spaces. If key authentication fails, first confirm the correct private key and username; do not repeatedly try different combinations.
Retest on another trusted network and temporarily rule out corporate proxies, VPNs, egress firewalls, and security software rules. Record the destination address, port, time, and timeout text.
Confirm that the address, username, and display settings saved by the client still match the current device. If the screen opens but input lags, lower the resolution and color quality first, then check for local network jitter.
Use verbose output to determine whether the failure occurs during resolution, the handshake, or authentication. If the handshake succeeds but authentication fails, focus on the username, private key, and authorized file. If the connection times out immediately, return to the network path.
ssh -vvv user@host
chmod 600 ~/.ssh/id_ed25519
ssh-add -lDo not submit passwords, private keys, recovery codes, complete payment credentials, or unredacted certificates in support requests. When showing configuration, include only fields relevant to the issue.
Xcode and signing
Do not use one full release job to validate every layer at once. Confirm the toolchain version first, validate signing with a test project, then return to the real project and inspect the archive log.
Confirm that the version selected in the GUI, the command-line path, and the project requirements match. After switching versions, reopen the terminal and build process.
xcode-select -p
Confirm that the required certificate and its private key are fully imported and accessible in the current login session. Seeing the certificate name alone does not confirm a successful import.
security find-identity -v -p codesigning
Verify the app identifier, team, capabilities, and validity scope. Save an inventory before removing old profiles so you can roll back.
~/Library/MobileDevice/Provisioning Profiles
If archiving works in the GUI but fails in CI, check the Keychain used by the Runner session, the unlock flow, and access controls.
security list-keychains
Find the earliest failure in the archive log rather than copying only the final summary. Record the target, configuration, SDK, and command used.
xcodebuild -showBuildSettings
CI/CD troubleshooting guide
Break CI issues into four layers: scheduling, execution environment, resources, and scripts. Re-running immediately only overwrites the evidence; it does not prove recovery.
| Symptom | Check first | Order of operations | Recovery criteria |
|---|---|---|---|
| Runner offline | Process, network, registration, execution user | Confirm the device is reachable, then read service logs; verify registration scope and startup user. Do not re-register first. | The Runner remains online and successfully picks up a minimal test job. |
| Job queued for too long | Tags, concurrency limit, existing jobs | Confirm the job tags match the Runner; check for unfinished processes or occupied execution slots. | A new job is picked up in the expected queue, and old jobs have a clear exit state. |
| Cache restore failed | Cache key, directory permissions, free disk space | Compare cache keys between successful and failed jobs; verify directory ownership, then clear rebuildable caches. | Dependencies restore successfully, and the next job reuses the same cache rules. |
| Script permission error | Execute bit, interpreter, working directory | Confirm the script is committed to the repository with its execute bit preserved; check the interpreter on the first line and relative paths. | The script runs successfully in the Runner user’s non-interactive session. |
| Build timeout | Last active stage, CPU, memory, disk | Find the last valid log entry first, then determine whether the process is blocked, resources are insufficient, or a network dependency is pending. | The same commit completes repeatedly, with duration close to baseline and no leftover processes. |
The health check should verify the working directory, disk, toolchain path, and one short test. It should not contain release credentials or depend on a large cache.
whoami
pwd
df -h
xcodebuild -version
git --versionPerformance and storage
One slow job is not enough to justify a larger configuration. Check Activity Monitor, disk capacity, and build logs together, and compare them with the normal baseline for the same project.
Observe the entire job cycle rather than a single moment. CPU at full utilization for a sustained period while the job progresses indicates compute load. Sustained memory pressure with heavy swapping indicates that concurrency or project size may exceed the current configuration.
First measure usage from the project, dependencies, simulators, archives, and rebuildable caches. When disk space approaches its capacity limit, dependency extraction, archiving, and log writes may all fail. Distinguish artifacts from rebuildable data before cleaning.
If resource curves look normal but the job stops at the same script, dependency download, or compile stage, check version changes, network dependencies, and script wait conditions. Comparing a successful log is faster than looking only at total duration.
Retest with lower concurrency. If duration changes consistently with concurrency, evaluate a larger configuration.
Clear rebuildable caches, archive old artifacts, and establish post-job cleanup rules.
Check scripts, dependency sources, toolchain versions, and non-interactive permissions.
Nodes and network
NUMACS offers nodes in Singapore, Japan (Tokyo), South Korea (Seoul), and Hong Kong. All directory combinations can be ordered; actual availability is returned in real time by the console.
Suitable for access from Southeast Asia and nearby networks. During diagnosis, record the local carrier, destination address, connection method, and time.
Choose Singapore nodeWhen connections are abnormal, test Remote Desktop and SSH separately, and note whether the issue occurs only on a specific local network.
Choose Japan nodeFor network issues, include the timeout or disconnection period and retest results from another network on the same device.
Choose South Korea nodeIf interactive latency changes suddenly, record the destination address, protocol, client version, and job running at the time.
Choose Hong Kong nodeProvide the time and time zone, node, destination address, protocol, local network type, complete error text, and retest results after switching networks. If you run diagnostic commands, submit redacted text output rather than isolated numbers from a screenshot.
Billing and billing cycles
Devices are available for daily, weekly, monthly, or quarterly rental. Orders are charged in US dollars (USD); the cycle and configuration are defined by the order record.
Suitable for short-term validation, temporary builds, or migration rehearsals. For billing questions, include the order start time and device identifier.
Suitable for a continuous sprint or release acceptance. Do not confuse a calendar week with the order’s actual cycle.
Suitable for stable development and continuous integration workflows. Export necessary data and confirm migration arrangements before upgrading the configuration.
Suitable for ongoing projects and dedicated Runners. Teams should document credential rotation, backups, and job handoff procedures in advance.
Review before submitting
The following details determine whether support staff can begin reproducing and locating the issue immediately instead of requesting basic information back and forth.
Confirm the device status in the console, then submit the order number, node, time and time zone, destination address, complete errors from both connection methods, and retest results from another local network. Do not submit passwords or private keys.
No. First save the first root-cause error, Xcode version, command-line tools path, project configuration, and recent changes. Reinstallation changes the evidence and may remove version differences and logs that identify the issue.
First check device connectivity, the Runner process, execution user, and service logs. Re-register only after confirming that the registration information is damaged or expired. Otherwise, old and new Runner records may coexist and make scheduling issues harder to diagnose.
Keep timestamps, commands, error codes, tool versions, and path structure relevant to the issue. Replace usernames, repository addresses, access tokens, certificate contents, private keys, and business data. Read the redacted version once more to confirm the context is still sufficient for reproduction.
State that it is a build issue in the subject and provide the order number, node, time, reproducible steps, expected result, actual result, and redacted logs. Requests are queued based on the completeness of the information; fuller context means fewer follow-up questions.
Escalate to human support
Prepare the order number, node, time and time zone, reproduction steps, expected result, actual result, attempted actions, and redacted logs. For existing orders, submit a support ticket in the console. For presales guidance, node questions, and billing issues, email support@numacs.com.