SwiftPM's Bundle.module crashes your Mac app on every machine but yours

Ritesh Sethia — Wed, 11 Nov 2026 20:02:23 +0000

I shipped a Mac app. It was signed, notarized, stapled, and verified by
Gatekeeper. 378 tests passed. I installed it from the DMG on my own machine and
used it for an hour.

A friend downloaded it. It crashed on launch. Not misbehaved — crashed,
instantly, every time, before a window appeared.

The cause is a generated accessor that most people never read, and it will do
the same thing to your app if you build a .app out of Swift Package Manager
targets that have resources.

What SwiftPM generates

When a target declares resources:, SwiftPM writes a file called
resource_bundle_accessor.swift into the build directory and compiles it into
your module. That file is what Bundle.module resolves to. It looks roughly
like this:

extension Foundation.Bundle {
    static let module: Bundle = {
        let bundleName = "Arazio_ArazioCore"
        let overrides: [URL] = [ /* SWIFT_PACKAGE_RESOURCE_BUNDLE_PATH, if set */ ]
        let candidates = overrides + [
            Bundle.main.resourceURL,
            Bundle(for: BundleFinder.self).resourceURL,
            Bundle.main.bundleURL,
        ]
        for candidate in candidates {
            let path = candidate?.appendingPathComponent(bundleName + ".bundle")
            if let path, let bundle = Bundle(url: path) { return bundle }
        }
        fatalError("unable to find bundle named Arazio_ArazioCore")
    }()
}

The exact candidate list has changed across toolchain versions, which is part
of why this is hard to pin down. The shape that matters has not changed: a
short list of guesses, and then fatalError.

And on some versions, one of those guesses — or the override baked in at
compile time — is an absolute path into the .build directory of the machine
that compiled the binary.

Why it works for you and nobody else

Run the app from Xcode or from swift run, and the bundle is sitting right
next to the executable in .build/release/. Found on the first or second
candidate. Everything works.

Now assemble a real .app. The convention — and what codesign expects, and
what every bundling script does — is that resources go in
Arazio.app/Contents/Resources/. But Bundle.main.bundleURL is
Arazio.app/, not Contents/Resources/. So that candidate misses.

On your machine, the fallback into .build still resolves, because that
directory is right there on your disk. The app finds its resources through a
path that has nothing to do with the bundle it is supposedly running from. Your
own development tree is silently propping up the shipped application.

On a customer's machine that path does not exist. Neither does any other
candidate. So: fatalError, on the first line of
applicationDidFinishLaunching, with a crash report naming a directory on a
stranger's disk.

Nothing in a normal pipeline catches this

This is the part worth sitting with. Every check I had was green:

swift build -c release — succeeded.
The full test suite — 378 tests, passing. They run on my machine, where the path exists.
codesign --verify --deep --strict — valid.
Notarization — accepted by Apple.
stapler validate and spctl --assess — accepted.
Installing from the DMG and using the app — worked perfectly.

Not one of those can see the problem, because every one of them runs on the
machine that has the .build directory. Apple's notary service checks that
your code is signed and free of known malware. It does not launch your app on a
clean machine and see whether it survives.

The only thing that catches this is a machine that is not yours.

The fix

Stop using Bundle.module for anything that ships inside a .app. Write a
lookup that checks where resources actually live, in order, and returns nil
instead of trapping:

public enum ResourceBundle {

    /// Anchors `Bundle(for:)` to this module, which is how the bundle is found
    /// under a test runner: there `Bundle.main` is the xctest tool, and none of
    /// the app-shaped paths exist.
    private final class Anchor {}

    public static func named(_ name: String) -> Bundle? {
        let filename = name.hasSuffix(".bundle") ? name : name + ".bundle"
        let candidates: [URL?] = [
            // Where an .app keeps them, and where the bundling script puts them.
            Bundle.main.resourceURL?.appendingPathComponent(filename),
            // Where SwiftPM's own accessor looks, in case that becomes right.
            Bundle.main.bundleURL.appendingPathComponent(filename),
            // Beside the executable, where a plain `swift build` leaves them.
            Bundle.main.executableURL?
                .deletingLastPathComponent()
                .appendingPathComponent(filename),
            // Under a test runner, or anything else that is not our .app: the
            // bundle sits beside the binary that contains this code.
            Bundle(for: Anchor.self).resourceURL?
                .appendingPathComponent(filename),
            Bundle(for: Anchor.self).bundleURL
                .deletingLastPathComponent()
                .appendingPathComponent(filename),
        ]
        for case let url? in candidates
        where FileManager.default.fileExists(atPath: url.path) {
            if let bundle = Bundle(url: url) { return bundle }
        }
        return nil
    }
}

Two details that are easy to get wrong.

Bundle.main.resourceURL goes first. That is Contents/Resources inside a
real .app, which is the correct answer and the one SwiftPM does not try
first.

The Anchor class is not optional. My first attempt at this fix dropped
the Bundle(for:) candidates, on the reasoning that an app-shaped lookup is
what an app needs. That broke 273 tests instantly. Under a test runner,
Bundle.main is the xctest binary, and none of the app paths exist — the
bundle sits beside the module's binary, which is what Bundle(for:) finds.
Returning nil rather than trapping also means a caller can fail with a message
a person can act on, instead of a stack trace.

Note the deliberate absence of a .build fallback. If the resources are not in
one of those five real locations, the app is broken and should say so — not
quietly borrow them from a directory that only exists here.

The part that actually matters

Fixing it is twenty minutes. Making sure it never happens again is the point,
and it is the part I would not have bothered with before this shipped broken.

A release cannot depend on me remembering to test on a borrowed Mac. So the app
grew a flag that loads everything it needs from its own bundle and exits,
without opening a window:

if CommandLine.arguments.contains("--verify-resources") {
    var failures: [String] = []

    if ResourceBundle.named("Arazio_ArazioCore") == nil {
        failures.append("Arazio_ArazioCore.bundle not found")
    }
    if ResourceBundle.named("Arazio_ArazioUI") == nil {
        failures.append("Arazio_ArazioUI.bundle not found")
    }
    do {
        let registry = try FormatRegistry.loadBundled()
        guard registry.allFormats.count > 1 else {
            throw FormatRegistry.LoadError.manifestMissing
        }
        print("  format manifest: \(registry.allFormats.count) formats")
    } catch {
        failures.append("FormatRegistry.loadBundled failed: \(error)")
    }
    // …every other resource the app needs to start

    exit(failures.isEmpty ? 0 : 1)
}

And the release script takes the prop away before running it — it moves the
build directory's resource bundles aside, asks the staged app to load
everything, then puts them back:

echo "==> Verifying the app stands on its own"
STASH="$BUILD/resource-stash"
BUILT_PRODUCTS="$(cd "$ROOT" && swift build -c release --show-bin-path)"
rm -rf "$STASH"; mkdir -p "$STASH"
shopt -s nullglob
STASHED=("$BUILT_PRODUCTS"/*.bundle)
shopt -u nullglob
for BUNDLE in "${STASHED[@]}"; do mv "$BUNDLE" "$STASH/"; done

restore_bundles() {
  shopt -s nullglob
  for BUNDLE in "$STASH"/*.bundle; do mv "$BUNDLE" "$BUILT_PRODUCTS/"; done
  shopt -u nullglob
  rmdir "$STASH" 2>/dev/null || true
}
trap restore_bundles EXIT

if ! "$APP/Contents/MacOS/Arazio" --verify-resources; then
  restore_bundles
  trap - EXIT
  echo "error: the app cannot find its own resources without this machine's"
  echo "       build directory. It would crash on launch for every customer."
  exit 1
fi
restore_bundles
trap - EXIT

The trap matters more than it looks. If the check fails, or the script is
interrupted between the two mv loops, the bundles have to go back — otherwise
a failed release leaves your working tree in a state where the next build is
also broken, for an entirely different reason.

This is, as far as I can tell, the only way to see what a stranger's Mac sees
without owning one.

If you take one thing

The bug was never really Bundle.module. The bug was that every check I had
ran on the machine that had the thing being tested for.

That is worth turning into a standing question rather than a one-off fix. What
else is true on my machine that is not true on a customer's? A Homebrew library
on the link path. A font. A permission granted months ago and forgotten. A
filesystem — a later release of the same app refused every conversion on exFAT
drives, because volumeAvailableCapacityForImportantUsage returns zero on
anything that is not APFS, and I only own APFS volumes.

Each of those is invisible to a test suite that runs where you build. The fix
is not to test harder. It is to make the release take away the thing you are
standing on, and see whether the app is still upright.

Written while building Arazio, a Mac app that converts files from the
drag itself. The crash described here was version 1.0.0, fixed in 1.0.1, about
six hours apart.