Remote Mac CI Disk Space Shortage: 2026 Troubleshooting Guide

GitHub-hosted jobs run on fresh runner instances, while self-hosted runners leave machine management to you, as GitHub’s runner documentation explains. If remote Mac CI reports low disk space, first identify whether the consumer is DerivedData, simulator data, archives, or the workspace. Then clean only data you have confirmed can be rebuilt or discarded. Do not delete the entire developer directory as a general fix.

Who this is for

iOS and macOS developers diagnosing failed builds or archives on a remote Mac.
CI engineers managing persistent macOS runners and recurring job leftovers.
Small-team operators deciding whether to clean data, change workflows, or add host capacity.

1. Triage the failure before deleting files

“Disk space unavailable” can describe different failures. A build may fail while writing an intermediate file. An archive may fail at a later stage. A host alert may be raised even when the current job has not yet hit a write failure. One log line does not establish a shared root cause.

Start by capturing the job name, timestamp, failing phase, working directory, and exact error. Note whether the problem appeared once or whether available space decreases across successive jobs. If the job writes an archive or test result, record whether that output was created and where it was expected to go.

On the affected host, check free space for the filesystem containing the workspace and Xcode data. df -h gives a filesystem-level view. Then inspect likely directories with du -sh and compare the results with the job’s paths. Run these commands as an account that can read the relevant directories; permission restrictions can make a partial measurement look smaller than the real usage.

Apple recommends checking storage on the Mac itself rather than inferring usage from a single label. Its guide to viewing Mac storage can help you inspect the system’s view, but CI diagnosis still requires measuring the actual workspace and developer-data paths used by your runner.

Scenario: An archive job fails after several successful builds, and the host alert arrives at roughly the same time. That is a clue, not a diagnosis. Compare the filesystem’s available space with the sizes of DerivedData, Archives, simulator data, and the job workspace before choosing a cleanup target.

2. Locate the directories consuming space

Use the filesystem measurement first, then check the relevant folders. Common Xcode locations include the DerivedData and Archives directories under the user’s developer library, but Xcode settings and the account running the job can change where outputs are stored. Confirm the paths on the actual host; do not assume that a command run under your login account describes a CI service account.

Apple’s Xcode documentation distinguishes build-generated data from archived products. Its Xcode release notes on build locations describe where generated files are stored, while Apple’s archiving troubleshooting notes cover archive-related behavior. Check the documentation alongside the paths configured in your project and workflow.

The table is a triage map, not a deletion policy. If you cannot tie a large directory to a particular job or project, gather more evidence before removing it. “System Data” is not a cleanup target by itself; use the paths and sizes you can verify.

3. Separate DerivedData from archives

Xcode DerivedData can include indexes, logs, and build products. Some content may be regenerable, but that does not make every file safe to remove at any time. A running build may still depend on files there, and logs may be the only useful evidence of an intermittent failure.

For macOS CI, treat DerivedData as a candidate only after checking the workflow’s build-data path, whether jobs share the directory, and whether you need the contents to investigate the failure. If a job is active, do not remove files it may still be using. If you decide to clean, scope the action to the relevant project or confirmed data rather than wiping the whole Xcode directory.

Archives have a different purpose. They are outputs you may need for distribution, release records, or later investigation. Do not equate a large Archives folder with disposable cache. Check the project’s retention policy and whether the archive has been copied to its intended storage before deleting it. If the failure occurred during archiving, preserve the failed job’s logs and inspect the archive destination before treating old archives as the cause.

A useful distinction is simple: DerivedData is build-generated developer data; an archive is a saved build output with a possible retention obligation. They can both occupy space, but the decision to remove them should follow different rules.

4. Check simulator runtimes and device data separately

Simulator runtime packages, simulator device data, and project build products are not interchangeable. A workflow can require a particular runtime even when another installed runtime looks unused. Device data can also contain state relevant to a test. Measure these categories separately and inspect the workflow’s selected simulator before removing anything.

Apple documents how to add additional simulators and how to download and install Xcode components. Use those references to understand the supported component-management process. Confirm the behavior for the Xcode version and runtime on your host; do not manually delete files managed by Xcode or macOS just because their names look unused.

A cautious sequence is:

• List the simulators and runtimes relevant to the workflow.
• Match the workflow’s destination to the runtime and device it actually uses.
• Check whether another job or project shares that runtime or device data.
• Remove a specific, confirmed-unneeded item using the supported management path.
• Measure the filesystem and rerun the affected test before repeating cleanup.

If the cleanup removes a runtime needed by a later job, that job may fail for a different reason. Record what you removed so a future failure is not mistaken for a disk-space recurrence.

5. Control residue on persistent self-hosted runners

A hosted runner and a persistent self-hosted Mac have different cleanup responsibilities. GitHub describes self-hosted runners as machines you manage. That makes workspace residue, cached data, logs, and disk monitoring part of your operating procedure. Do not assume that the next task will receive a clean machine.

Separate cleanup targets by purpose:

• Workspace: files checked out or generated for a job. Scope cleanup to the repository and job lifecycle.
• Build data and caches: files that may be reusable or regenerable. Define which workflows own them and when they expire.
• Archives and test outputs: artifacts that may need to be retained or transferred before cleanup.
• Credentials and configuration: sensitive material that must not be swept into a general cache-removal rule.

Avoid a single command that deletes workspace, cache, archive, and credential directories together. That can remove evidence, break a later workflow, or erase data that should have been handled under a separate retention policy. If you use containers, review how the runner mounts and manages their data; GitHub documents options for customizing containers on self-hosted runners.

For recurring jobs, capture filesystem availability before and after each job or at a cadence appropriate to your workload. Compare the trend by path, not just by total free space. A stable cache that reaches a plateau calls for a different response from a workspace that grows on every run. Set alerts against the filesystem used by the job, and make the alert lead to a directory-level investigation rather than an automatic broad deletion.

6. Verify the cleanup with a real job

A cleanup is not confirmed just because the alert disappears. Run a representative workflow that exercises the failing stage. For a build failure, build the affected project. For a simulator failure, run the relevant test destination. For an archive failure, create and save a new archive using the workflow’s normal destination.

Apple’s build and run guidance is useful when checking the expected build flow. Compare the result with the original failure: did the same phase complete, were the expected outputs created, and did the next job start successfully?

Use this verification checklist before closing the incident:

• [ ] Record the filesystem and available space that affected the job before cleanup.
• [ ] Record the exact directory or item removed and why it was considered safe.
• [ ] Confirm no active job depended on the files being removed.
• [ ] Run the same build, test, or archive stage that failed.
• [ ] Verify that expected artifacts and logs were saved to the intended location.
• [ ] Check available space again and compare the same directory measurements.
• [ ] Run a subsequent job to check that cleanup did not break the next task.
• [ ] If space starts falling again, investigate the growth trend before repeating cleanup.

If the job passes but free space immediately returns to its previous level, the incident may be recurring rather than resolved. Keep the before-and-after measurements with the job record. Then decide whether to adjust retention, change cache behavior, split workspaces, or provide more host capacity. Do not infer that a single successful run proves the host has enough capacity for future workloads.

FAQ

How do I investigate a disk-space error during an Xcode build on a remote Mac?

Capture the job, failing phase, working directory, and exact error. Check filesystem availability, then measure the workspace and Xcode data locations instead of relying only on a macOS storage label. Compare with a successful run if possible. A build write failure, archive failure, and host alert can have different causes, so identify the affected path before deleting anything.

Can I delete Xcode DerivedData from a macOS CI machine?

Treat DerivedData as a cleanup candidate, not an automatic fix. It can contain indexes, logs, and build products, and a later build may regenerate some of them. Before removing anything, check whether jobs share the directory, whether a build is running, and whether you need its logs for diagnosis. Measure the directory again after a controlled cleanup.

How can a self-hosted macOS runner avoid accumulating build caches?

Separate job workspaces, reusable dependency caches, Xcode-generated data, archives, and credentials. Define what each workflow may remove and when; do not use one blanket deletion rule for every path. Record free space before and after jobs, investigate repeated growth, and alert on the filesystem that actually hosts the workspace and Xcode data.

How can I confirm Xcode works after cleaning simulator data?

Check which simulator runtime and device the affected workflow uses, and confirm the cleanup target is not active or required by another job. Then run a representative build and simulator test, verify that results and artifacts are saved, and check disk availability again. Keep before-and-after measurements with the job log to distinguish recovery from a temporary success.

Start with the failed project’s cleanup and verification, not a full-directory purge. A local Mac keeps the hardware and maintenance with your team; a Linux host cannot replace macOS-specific build tools; and a persistent self-hosted Mac still needs workspace cleanup and capacity monitoring. If the issue is temporary demand or a test environment you do not want to maintain permanently, compare that workload with a remote Mac environment or the available Mac mini options. If you need a short-lived Mac for CI validation, MangoVM may fit better than buying hardware; for continuous heavy workloads or a required physical connection, a dedicated local machine may be the better choice.

Frequently asked questions