Diagnosing Swift Compiler Crashes on a Cloud Mac

The same commit may build successfully on a development machine yet cause swift-frontend to exit abnormally during continuous builds on a cloud Mac. A rerun might occasionally succeed, only for a different file to fail after the cache is cleared. The most dangerous response is to modify the source, update dependencies, and delete every cache at the same time. Doing so changes the entire environment and may eliminate the condition that triggered the compiler crash. A safer approach is to identify the type of failure first, then narrow it down by changing one variable at a time.

Confirm That It Is a Compiler Crash

A CompileSwiftSources failure does not necessarily mean the compiler crashed. Syntax errors, type-inference failures, and missing modules can also return a nonzero status at this stage. The following signals indicate that the workflow in this article is appropriate:

• The log explicitly states that swift-frontend exited abnormally or received signal 11.
• The output contains a Stack dump, an internal assertion failure, or a compiler call stack.
• A matching swift-frontend report appears in ~/Library/Logs/DiagnosticReports/.
• The same source and command reproduce the failure repeatedly, rather than only during a one-off remote-session interruption.

Record the toolchain and host details first. Do not capture only the last ten lines of the log:

mkdir -p diagnostics
{
  date -u
  sw_vers
  uname -m
  xcode-select -p
  xcodebuild -version
  xcrun swiftc --version
} | tee diagnostics/environment.txt

find "$HOME/Library/Logs/DiagnosticReports" \
  -maxdepth 1 -type f -name 'swift-frontend*' \
  -exec cp {} diagnostics/ \;

The crash report, complete build command, and triggering source must all come from the same reproduction attempt. Combining artifacts from separate runs often creates misleading clues that cannot be verified.

Preserve the Initial State with an Isolated Build

Create a dedicated DerivedData directory for reproduction and save the complete terminal output. Do not begin by deleting global caches, because whether a cache contributes to the crash is itself a variable that must be tested.

set -o pipefail
rm -rf "$PWD/.diagnostics-derived-data"

xcodebuild \
  -workspace App.xcworkspace \
  -scheme App \
  -configuration Debug \
  -destination 'generic/platform=iOS Simulator' \
  -derivedDataPath "$PWD/.diagnostics-derived-data" \
  -jobs 1 \
  build 2>&1 | tee diagnostics/build-single-job.log

Reducing concurrency to one here is only a diagnostic step to determine whether the crash depends on parallel compilation. It is not a recommended long-term configuration. If the compiler still crashes consistently with a single job, preserve that log. If the failure disappears, keep the source and DerivedData fixed, then test -jobs 2 and the usual concurrency setting separately. Repeat each configuration at least three times, recording whether the result was a success, a normal compilation error, or a compiler crash. Do not record every outcome simply as “failed.”

When reproducing the problem on an OVPS cloud Mac, also record the Xcode path that was actually selected. Comparing only the version name shown in the interface is insufficient: builds and Swift toolchains can still differ within the same major Xcode release.

Build a Single-Variable Comparison Matrix

Start with variables that are inexpensive to test and cause the least disruption. Change only one item at a time and save each run to a new log.

Do not switch Xcode, update dependencies, and clear caches simultaneously. If changing the toolchain makes the problem disappear, that establishes only that the failure is related to the toolchain combination; it does not prove that the newer version has fixed the issue. Record the failing file, compilation mode, and number of occurrences in the same table as well.

Identify Cache-Related False Signals

Investigate module caches and the build database only when an empty DerivedData directory succeeds while the old directory fails consistently. Archive the problematic directory first, then clean only the relevant artifacts. Broad deletion removes the opportunity to compare old and new build products.

Reduce the Failing File to a Minimal Reproduction

Locate the failed Swift compilation task in the complete log. If the problem can be reproduced outside the project, copy the relevant declarations into Repro.swift and begin by checking the file’s types:

xcrun swiftc -typecheck Repro.swift 2>&1 | tee diagnostics/repro.log

Reduce the source in the reverse order of its dependencies: remove unrelated methods first, followed by protocol conformances, generic constraints, and property wrappers. Run the test script after every removal. Do not assume that code is responsible merely because its syntax looks complex. Compiler crashes are often triggered by combinations of two otherwise ordinary language features.

#!/bin/zsh
set -o pipefail

output="$(mktemp)"
xcrun swiftc -typecheck Repro.swift >"$output" 2>&1

if grep -Eiq 'signal 11|segmentation fault|stack dump|swift-frontend.*failed' "$output"; then
  cp "$output" diagnostics/latest-crash.log
  rm -f "$output"
  exit 0
fi

rm -f "$output"
exit 1

This script treats “the target crash still occurs” as success, making it suitable for manual bisection or source-reduction tools. After every reduction, verify that the failure signature remains the same. If an internal assertion turns into an ordinary type error, a required triggering condition has been removed.

If a single-file reproduction is not possible, preserve the smallest viable module boundary: a minimal project, the required build settings, pinned dependency versions, and one command that runs the test. Do not include business data, access credentials, or unrelated resources.

Create a Reviewable Handoff Package

The final package should allow someone to verify the issue on another cloud Mac without verbal instructions. The directory should contain only:

• README.md: expected behavior, execution command, repetition count, and actual results.
• environment.txt: system architecture, Xcode build number, and Swift version.
• Repro.swift or a minimal project: only the required source.
• build.log: complete, untruncated standard output and standard error.
• Crash report: the diagnostic file whose timestamp matches the run.
• check.sh: an exit status that clearly indicates whether the target crash was reproduced.

Before handing it off, run everything once more from a new directory. Confirm that the script does not depend on absolute paths from the original project, the user’s home directory, or residual module caches. If the issue occurs only at a specific concurrency level, document the concurrency parameter and reproduction rate. If it occurs only with a particular toolchain build, also record a comparison version that succeeds. The result is not merely a statement that “Swift crashes occasionally,” but a body of engineering evidence that can be reproduced, compared, and used to continue working toward a fix.

Frequently asked questions