iOS: dyld crash after updating to 1.11.2 — powersync-sqlite-core.framework not embedded

[thomasflad]

Description

After updating from PowerSync Kotlin 1.11.1 to 1.11.2 (and powersync-sqlite-core-swift from 0.4.11 to 0.4.12), the iOS app crashes at launch with a dyld error:

dyld: Library not loaded: @rpath/powersync-sqlite-core.framework/powersync-sqlite-core
  Referenced from: NotPink.app/NotPink.debug.dylib
  Reason: tried: '…/NotPink.app/Frameworks/powersync-sqlite-core.framework/powersync-sqlite-core' (no such file)

The KMP shared framework (NotPink.debug.dylib) dynamically links powersync-sqlite-core.framework via @rpath, but the framework is not present in the app bundle's Frameworks/ directory.

Reverting to 1.11.1 + 0.4.11 resolves the issue.

Environment

• PowerSync Kotlin SDK: 1.11.2 (was 1.11.1)
• powersync-sqlite-core-swift: 0.4.12 (was 0.4.11)
• Kotlin: 2.1.x
• Xcode: 26.0
• iOS target: 26.0
• Project setup: Kotlin Multiplatform with Tuist-generated Xcode project

Setup

The iOS app declares powersync-sqlite-core-swift as an SPM dependency and references it in the app target. The KMP shared framework is built via ./gradlew :shared:embedAndSignAppleFrameworkForXcode.

With 1.11.1 / 0.4.11, the app launches fine — powersync-sqlite-core does not appear as a dynamic dependency of the shared framework.

With 1.11.2 / 0.4.12, the shared framework (NotPink.debug.dylib) gains a dynamic link to @rpath/powersync-sqlite-core.framework/powersync-sqlite-core, which is not automatically embedded in the app bundle by the build system.

Expected behavior

The PowerSync Kotlin SDK should either:

1. Statically link powersync-sqlite-core into the shared framework (as it appeared to do in 1.11.1), or
2. Document that powersync-sqlite-core.framework must be manually embedded in the iOS app bundle, with setup instructions for common project configurations (SPM, CocoaPods, Tuist, etc.)

Steps to reproduce

1. Create a KMP project using com.powersync:core:1.11.2
2. Add powersync-sqlite-core-swift 0.4.12 as an SPM dependency in the iOS app
3. Build and run on iOS simulator
4. App crashes at launch with the dyld error above

Workaround

Pin to com.powersync:core:1.11.1 and powersync-sqlite-core-swift:0.4.11.

[simolus3]

Thanks for the report! I couldn't reproduce the issue in our demo project, but I'll try a new project as well. Some initial thoughts:

Statically link powersync-sqlite-core into the shared framework (as it appeared to do in 1.11.1), or

We've never actually linked the powersync-sqlite-core framework directly in the native SDK, it has always been loaded manually:

powersync-kotlin/common/src/nativeMain/kotlin/com/powersync/db/NativeConnectionFactory.kt

Lines 24 to 31 in c47e417

	if (extensionPath != null) {
	try {
	db.loadExtension(extensionPath, "sqlite3_powersync_init")
	} catch (e: PowerSyncException) {
	db.close()
	throw e
	}
	}

powersync-kotlin/common/src/appleMain/kotlin/com/powersync/PathUtils.kt

Lines 31 to 42 in c47e417

	internal val powerSyncExtensionPath: String by lazy {
	// Try and find the bundle path for the SQLite core extension.
	val bundlePath =
	NSBundle.bundleWithIdentifier("co.powersync.sqlitecore")?.bundlePath
	?: // The bundle is not installed in the project
	throw PowerSyncException(
	"Please install the PowerSync SQLite core extension",
	cause = Exception("The `co.powersync.sqlitecore` bundle could not be found in the project."),
	)
	// Construct full path to the shared library inside the bundle
	bundlePath.let { "$it/powersync-sqlite-core" }

(arguably we should link the extension statically to avoid this entire class of problems, but that's the current situation).

Document that powersync-sqlite-core.framework must be manually embedded in the iOS app bundle, with setup instructions for common project configurations (SPM, CocoaPods, Tuist, etc.)

It doesn't really have to be embedded - we load that framework at runtime, but it's still surprising to me that it ends up being a link-time dependency referenced with @rpath.

[simolus3]

I also can't reproduce the issue in a fresh project. I've created one via the KMP plugin in Android studio and set up a local PowerSync database to run a single query when the app starts. Without further setup, I get a "Please install the PowerSync SQLite core extension" error but the app itself can still load. Adding the dependency (as explained in our docs) makes everything work for me.

I suspect the tuist / SPM setup might be contributing to this issue. But I'll also note we didn't have any build setup changes between 1.11.1/0.4.11 and 1.11.2/0.4.12. So I'm a bit worried this might just be a weird cache issue where the old version accidentally works for you. If you can reproduce this in a fresh project I could checkout, that would be very helpful for us!

[thomasflad]

Hey @simolus3 — here's a minimal Tuist project that reproduces this: https://github.com/thomasflad/tuist-xcframework-embed-repro

3 files, one dependency (powersync-sqlite-core-swift 0.4.12). Steps:

tuist install && tuist generate --no-open

xcodebuild build \
  -workspace PowerSyncRepro.xcworkspace \
  -scheme App \
  -destination 'platform=iOS Simulator,OS=latest,name=iPhone 16 Pro'

# Install and launch on simulator
xcrun simctl install booted .../App.app
xcrun simctl launch --console-pty booted com.test.powersync-repro
# → dyld: Library not loaded: @rpath/powersync-sqlite-core.framework/powersync-sqlite-core

What's happening

You're right that this is Tuist-specific. The powersync-sqlite-core-swift SPM package exposes the .binaryTarget directly as its product:

products: [.library(name: "PowerSyncSQLiteCore", targets: ["PowerSyncSQLiteCore"])],
targets: [.binaryTarget(name: "PowerSyncSQLiteCore", url: "...", checksum: "...")]

When Tuist resolves this, it links the dynamic XCFramework (adds to "Link Binary With Libraries") but does not embed it (missing from "Embed Frameworks" build phase). The framework ends up in the build products directory but not inside App.app/Frameworks/.

Xcode's Run action masks the bug by injecting DYLD_FRAMEWORK_PATH at launch, so the dynamic linker finds the framework in the build products dir. But simctl launch, release builds, and App Store builds will crash.

Why OneSignal works but PowerSync doesn't

Other SPM packages with binary XCFrameworks (like OneSignal-XCFramework) use a source wrapper target pattern:

products: [.library(name: "OneSignalFramework", targets: ["OneSignalFrameworkWrapper"])],
targets: [
    .target(name: "OneSignalFrameworkWrapper", dependencies: ["OneSignalFramework"]),
    .binaryTarget(name: "OneSignalFramework", ...)
]

This indirection lets Tuist correctly traverse the dependency graph and embed the XCFramework. The direct product → binaryTarget pattern does not.

Possible fixes

This is ultimately a Tuist bug, but adopting the source wrapper pattern in powersync-sqlite-core-swift would work around it and improve compatibility with Tuist projects today.

[simolus3]

Thanks for the investigation, that's helpful to know!

adopting the source wrapper pattern in powersync-sqlite-core-swift would work around it and improve compatibility with Tuist projects today.

Starting with powersync-ja/powersync-sqlite-core#172, we can change how we link the target from Kotlin. Instead of requiring users to add a dependency on their own, we can use cinterop with Kotlin/Native to link the core extension into the Kotlin app directly. I think that should fix this issue as well.

[thomasflad]

Thanks @simolus3, I guess this would be a great option! I'm just wondering why this issue starts to appear with the update to 1.11.2, do you have an idea?