First classify the issue as a connection, development environment, CI/CD, storage, network, or account-management problem. Then verify status, parameters, and logs in a fixed order. Oakmini provides dedicated physical Mac mini nodes, not virtual machines; troubleshoot local connection conditions, node status, and project toolchains separately.
$ uname -m
arm64
$ sw_vers -productVersion
macOS ready
$ ssh -v oak-node
debug1: Authentication succeeded
$ df -h /
Filesystem status: availableDo not change the network, credentials, and tool versions at the same time. Choose the closest symptom, verify one variable at a time, and record the time, action, and result. This prevents one change from hiding another issue.
For SSH timeouts, a black VNC screen, rejected credentials, or connections that drop immediately.
Start with host statusFor mismatched Xcode paths, Homebrew packages, Git settings, Fastlane, or language runtime versions.
Check paths and version inventoryFor offline runners, mismatched tags, queued jobs, cache problems, or incomplete build output.
Start with runner registration statusFor low disk space, growing caches, disorganized work directories, or build artifacts that cannot be exported.
Check capacity, directories, and usageFor increased interactive latency, intermittent packet loss, slow file transfers, or access failures limited to a specific local network.
Compare routes and time periodsFor order identification, host-management permissions, renewal status, or console actions that have not updated.
Start by checking the order and activity logUse df -h to view volume capacity, then use du -sh to check project, build-cache, and export directories. Confirm that artifacts are backed up before deleting anything; do not empty unknown system directories.
Record SSH connection time, VNC interaction time, code checkout time, and local build time separately. If only the graphical interface is slow, adjust VNC quality first. If both the command line and transfers are affected, check the local route and node reachability.
Confirm the signed-in account, order ID, selected region, and time of the latest action. Host status, orders, and management actions are handled in the console; include only the order ID in support requests and never send login credentials.
Connection failures usually occur in one of five layers: host status, local network, connection parameters, firewall, or credentials. Verify them in order; do not change the next layer until the previous one passes.
Confirm that the Cloud Mac linked to the order is connectable, and verify that the node region and connection details refer to the same physical node. If you have just completed a management action, record the action time and current status instead of repeatedly submitting the same action.
Pass condition: Host status is normal, and the order ID, node region, and connection target match.First confirm that the local network can reach the target address and port, then compare it with another trusted network. Check egress policy only when the office network fails. If every network fails, retain the test time, target port, and error type.
nc -vz HOST PORT
ssh -vvv USER@HOSTConfirm that the host address, port, username, and connection method come from the current order. SSH config aliases may override the port or key path; use verbose logs to see the parameters actually applied. For VNC, verify the target address, display settings, and old records saved by the client.
ssh -G oak-node
ssh -v USER@HOST -p PORTRecord existing rules before temporary testing. Check whether the terminal, SSH client, or VNC client is allowed to initiate connections, and whether the corporate network restricts the target port. Do not disable all local protection for an extended period just to troubleshoot.
Pass condition: The target application and port have explicit outbound permission, and the alternate-network test produces the same result.Distinguish between “network timeout” and “authentication rejected.” A timeout should not be solved by changing the password. For a rejection, confirm the username, key file, file permissions, and whether credentials were recently changed. Support requests may include the authentication error text only—never passwords or private-key contents.
chmod 600 ~/.ssh/id_ed25519
ssh-add -l“Installed” does not mean “used by the pipeline.” Toolchain troubleshooting should record executable paths, versions, the current shell environment, and the project’s actual invocation result.
| Tool | Check first | Suggested command | Common mismatch |
|---|---|---|---|
| Xcode | Active developer directory, version, and SDK list | xcode-select -pxcodebuild -version |
The command line points to another Xcode installation, or the project’s required SDK is missing from the active version |
| Homebrew | Binary path, package list, and diagnostic result | brew --prefixbrew doctor |
The shell has not loaded the correct path, or the package list differs from the local environment after migration |
| Git | Version, remote URL, repository permissions, and user configuration | git --versiongit remote -v |
The runner and interactive shell use different credentials or working directories |
| Fastlane | Invocation source, locked dependencies, lane, and environment-variable names | bundle exec fastlane --version |
The global version is called directly instead of using the project dependency file |
| Language runtime | Interpreter path, version manager, and project-pinned version | which rubywhich node |
The interactive shell and non-interactive job load different initialization files |
Record the macOS version, chip architecture, Xcode version, Homebrew package list, Git version, and language runtimes. Change one major component at a time during upgrades, and save the inventory both before and after each upgrade.
When a command works in the local terminal but fails in the runner, add echo "$PATH", which and version commands to a temporary diagnostic step. Remove unnecessary environment output afterward to prevent sensitive variables from appearing in logs.
Run dependency resolution first, then a clean build, and finally confirm the artifact path and exit code. If the minimal project succeeds but the production project fails, continue with project configuration, dependency locks, and script permissions.
The following output is enough to establish a baseline version record. Remove project names and any sensitive parameters from the directory before submitting a support request.
uname -m
sw_vers
xcode-select -p
xcodebuild -version
brew --prefix
git --version
which ruby
which node
df -h /Evaluate CI/CD issues layer by layer: whether the runner accepts the job, enters the work directory, has the required permissions, finds the dependencies, and completes the build. Do not rely only on the final failure message.
Confirm that the runner service is running, its registration is still valid, and the console shows it online. Before restarting, record the last online time and the most recent successful job.
When a job remains queued while the runner is online, compare the tags required by the job with the runner’s actual tags. Differences in case, spaces, or architecture can prevent the job from being picked up.
Confirm that the runner user has the required permissions for repository, cache, and artifact directories. Do not hide a single path configuration error by broadly expanding permissions across all directories.
When a cache becomes invalid, first run a comparison job without reading the old cache. If concurrent jobs overwrite one another’s files, assign each job an independent working directory and check whether Oak Core or Oak Forge has enough memory and storage for the workload.
Retain the job start time, runner name, commit ID, key tool versions, failed step, exit code, and final log section. If the failure is reproducible, record the shortest reproduction steps. If intermittent, retain at least one successful and one failed comparison.
Check runner online status, project authorization, and tags first. Do not clear the cache yet, because the job has not entered the build stage.
Check the working directory, script permissions, shell initialization, and tool paths first. Compare environment variables in the interactive terminal and runner.
Check lockfiles, cache keys, available disk space, and network download logs. Use one clean-cache job for comparison; do not repeatedly overwrite the original evidence.
Check memory usage, shared-directory write conflicts, port usage, and temporary-file naming. Reduce concurrency to validate the cause before changing job partitioning or configuration.
Consistent terminology reduces back-and-forth. When describing an issue, identify the specific object—for example, “SSH connection timeout on the Tokyo node” rather than simply “server unavailable.”
Oakmini offers two contact channels: submit a ticket after signing in to the console, or email support@oakmini.com. Use a ticket first for existing orders, host status, and ongoing troubleshooting; use email for presales questions or when you cannot access the console.
Fill in each item; write “Not confirmed” for unknowns instead of guessing. If the issue involves multiple attempts, list them in chronological order.
Subject: Order ID / issue category / node region
Occurrence time and time zone:
Connection method or job type:
Expected result:
Actual result:
Reproduction steps:
1.
2.
3.
Troubleshooting completed:
Original error text and exit code:
Description of redacted log attachments:The support page provides troubleshooting sequences, commands, and guidance for preparing information. Place orders, renew service, view orders, confirm host status, and manage your Cloud Mac in the console. All nodes operate normally 365 days a year. If the status differs from the actual connection result, record the time and submit a ticket.