How to Fix “JITError: Runtime linking failure / Symbols not found” in Xcode

When a SwiftUI preview reports “JITError: Runtime linking failure” and “Symbols not found,” the preview process cannot load one or more Swift symbols it needs. Identify the package or framework that owns the first missing symbol, then verify that the dependency reaches the target being previewed.

Typical error
Common conditions
Recommended fix
Alternatives
How to verify the fix
Important notes
Summary
References

Typical error

JITError: Runtime linking failure
Additional Link Time Errors:
Symbols not found:
  _$s...

A normal app build may still succeed because previews load code into a separate runtime environment. Transitive package dependencies, static libraries, conditional targets, and binary frameworks with incomplete architecture support can therefore fail only in the preview.

Common conditions

A Swift package is used indirectly through another package or framework.
The package product is not linked to the target that contains the preview.
The importing target is missing a product dependency in Package.swift.
Static and dynamic products or XCFrameworks are mixed incorrectly.
A binary dependency has no compatible Simulator slice.
Package.resolved or Derived Data still represents an older dependency graph.

Recommended fix

1. Identify the owner of the missing symbol

Open the preview diagnostics and inspect the first missing symbol. Decode a mangled Swift name with:

xcrun swift-demangle '_$s...'

The decoded module name usually points to the package product or framework that is absent. Fix that module first before chasing the rest of the list.

2. Link the dependency to the correct target

For an Xcode project, inspect General > Frameworks, Libraries, and Embedded Content and Build Phases > Link Binary With Libraries for the app or framework target that owns the preview. Add the required package product to the target that imports it.

Inside a Swift package, declare the product in the importing target:

.target(
    name: "FeatureUI",
    dependencies: [
        .product(name: "Numerics", package: "swift-numerics")
    ]
)

A dependency linked by the top-level app is not automatically a valid dependency of every framework or package target below it. Declare the dependency on the target that uses the module.

3. Check platform and binary compatibility

Confirm that the package deployment requirement supports the preview Simulator OS.
Verify that an XCFramework contains a compatible Simulator slice.
Do not mix binary artifacts produced by incompatible Xcode or Swift toolchains.
Remove duplicate paths that add the same library more than once.

lipo -info path/to/Binary
file path/to/Binary

4. Resolve packages and rebuild

Choose File > Packages > Resolve Package Versions.
Choose Product > Clean Build Folder.
Close and reopen the preview.
Delete Derived Data only when stale products are still suspected.

If clearing caches appears to fix the issue, verify the dependency declaration in a clean checkout or CI environment so the error does not return.

Alternatives

Use preview-specific mock data and avoid initializing an external SDK in the preview process.
If a binary SDK lacks a Simulator slice, obtain a compatible build or replace it with a preview stub.
Run the app normally on the same Simulator to separate a preview-only failure from a general link failure.
If only one Xcode release fails, use a verified version temporarily and retest with the latest stable Xcode.

How to verify the fix

The app builds and runs on the target Simulator.
The missing-symbol section disappears from preview diagnostics.
The preview can be regenerated after removing Derived Data.
Package resolution and compilation succeed on CI or another Mac.

Important notes

Do not add -all_load or -force_load indiscriminately. Those flags can introduce duplicate symbols and increase binary size. Use them only after identifying the library and following its vendor’s integration instructions.

As of September 16, 2026, Apple has not identified one universal fixed Xcode release for every instance of this error. Treat it as a dependency and runtime-linking diagnosis first, rather than assuming a single Xcode defect.

Summary

This JITError means that the preview runtime is missing linked code. Demangle the first symbol, find its module, declare the package product on the target that uses it, and verify Simulator architecture and deployment compatibility. Then resolve the package graph and rebuild in a clean environment.