Library not loaded: @rpath/libswiftCompatibilitySpan.dylib – Building bundle target

Thanks for the post.

Based on your description, you are encountering an issue with loading the library and deploying it into macOS versions 15?

I believe there was a bug on previous versions of Xcode, but that should have been fixed. Are you using Xcode 26.2 to build the app?

The error message indicates that the library cannot be found at runtime, despite being included in your build setup.

If you are getting this error on macOS Sonoma with the app build in Xcode 26.2, it means the bug is on that version of macOS. If you are not getting the error in macOS Tahoe, the bug has been fixed. The good news is that the bug has been fixed, but the bad news is that the bug is also in macOS 15? And it was not just Xcode as I initially thought.

Can you confirm that when you deploy the app built in Xcode 26.2 to macOS 15, you still encounter this bug?

Albert Pascual
  Worldwide Developer Relations.

Based on your description, you are encountering an issue with loading the library and deploying it into macOS versions 15?

Correct.

Can you confirm that when you deploy the app built in Xcode 26.2 to macOS 15, you still encounter this bug?

That is the case. I sm compiling with Xcode 26.2 using macOS 26.2 (25C57) SDK (Built-in) targeting macOS 12 and later.

The error occurs on macOS 15.7.3 but not on macOS 26. I suspect this is because macOS provides the Span API natively and thus does not need to access the backdeployment dylib, unlike macOS 15 where this API is not available natively.

Talking to people working on Swift, they interpreted this to be an Xcode issue, stating:

Xcode should (somehow) bundle libswiftCompatibilitySpan with it, but it doesn’t, leading to the failure on macOS 15.x.

So the only option right now is to download an OSS toolchain from swift.org?

@await May I ask you to create a bug for that as should not be failing in macOS 15.x as far as I know this issue was fixed in Xcode, not in macOS.

Once you open the bug report, please post the FB number here for my reference.

If you have any questions about filing a bug report, take a look at Bug Reporting: How and Why?

Albert Pascual
  Worldwide Developer Relations.

Thanks for looking into this. When you say “as far as I know this issue was fixed in Xcode, not in macOS”, do you mean I should report a bug for macOS, not Xcode?

A bugfix update for macOS 15 would not help me deploy my software to older OS versions since I cannot rely on users of older OS versions to update to the bugfixed OS version in a timely manner.

As far as I can tell, Xcode is not including the comparability dylib in the compilation of the bundle. Thus, the bug would need to be fixed in Xcode.

I figured out a workaround: Add a new “Copy Files” build phase to the target with the destination “Frameworks” with the following file

/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/swift-6.2/macosx/libswiftCompatibilitySpan.dylib

That is, copying the libswiftCompatibilitySpan.dylib file manually into the “Frameworks” directory of the bundle.

The bundle now loads on older OS versions like macOS 15. However, this workaround is not a good solution as it requires me to manually find the libswiftCompatibilitySpan.dylib file and ensure to keep its path updated in the Xcode project settings each time the toolchain is updated.

Ideally, Xcode would recognize that libswiftCompatibilitySpan.dylib is linked using rpath and include the file in the “Frameworks” directory automatically. Maybe there is a build setting that I need to enable that would do this, but I could not find anything.

Thank you for your post and the valuable workaround information provided. Very interesting!

Managing dynamic libraries and ensuring compatibility across various macOS versions can indeed be a complex task. The manual workaround you have implemented is highly intelligent and an effective approach when dealing with missing runtime libraries on older systems, but should not be missing in macOS as far as I know. However, automating this process would undoubtedly enhance maintainability.

In my opinion, it would be beneficial to have a bug report indicating the issue in macOS 15. Instead of hardcoding the path to, you can utilize to dynamically locate it. This approach can make your build script more resilient to changes in Xcode toolchain paths. Modify your “Copy Files” build phase to include a script that utilizes, ensuring its adaptability.

Given your belief that Xcode should handle this better, and I concur, consider submitting feedback to Apple on your bug report, even if the target is macOS 15 in this case.

As an alternative to a build phase script, a custom post-build script could also automate the copying of necessary files once the build completes.

Albert Pascual
  Worldwide Developer Relations.

To test my suspicion that this is an Xcode issue and not macOS 15 issue, I used Swift Package Manager to built a small executable instead of building it with Xcode. The complete software (using the new Span API) is this:

import Foundation

@main
struct App {
	static func main() {
		let data = Data([1, 2, 3, 4, 5])
		let span = data.span
		print(span[2])
	}
}

using this Package.swift file

// swift-tools-version: 6.2
import PackageDescription

let package = Package(
	name: "span-compat-test",
	platforms: [.macOS(.v13)],
	targets: [.executableTarget(name: "span-compat-test")]
)

I make an executable by running swift build -c release on macOS 26 using Apple Swift version 6.2.1 (swift-6.2.1-RELEASE).

The resulting executable runs on macOS 26, macOS 15, and macOS 14. I have not tested older OS versions.

So, SwiftPM is able to compile the executable in a way that runs on older OS versions while in Xcode I currently require a manual workaround.