SwiftUI Preview “Failed to build the scheme”: Causes and Fixes

What causes this error?

The message appears when Xcode cannot complete the build that Preview needs. Common causes include ordinary compiler errors, the wrong scheme or target, unresolved Swift Package dependencies, missing Target Membership, incompatible deployment settings, failing preview-only initialization code, and stale Derived Data or build caches.

Common situations

• The app builds inconsistently after editing SwiftUI code
• The error appears after adding or updating a Swift Package or CocoaPods dependency
• You switched schemes, targets, or Git branches
• You changed the deployment target or SDK
• Your preview initializes real networking, databases, Keychain access, or other runtime services

How to diagnose it

Start by running a normal build instead of focusing only on the Canvas error.

Product > Build

Then check that the correct scheme and run destination are selected. If the Canvas is paused, restart the preview. Current Xcode versions also provide Preview diagnostics from the Canvas, which can help identify the underlying build failure.

Fix 1: Resolve normal build errors first

SwiftUI Preview does not compile only the visible view in isolation. Xcode may need to build the target and linked modules. A compiler error elsewhere in the target can therefore prevent the preview from building.

struct ContentView: View {
    var body: some View {
        Text("Hello")
    }
}

#Preview {
    ContentView()
}

Fix 2: Select the correct scheme and target

In projects with multiple schemes or targets, select the scheme that actually contains the SwiftUI file you want to preview. Also open the File Inspector and confirm that the file belongs to the required target under Target Membership.

Fix 3: Resolve Swift Package dependencies

If package resolution is failing, review Package Dependencies and resolve them again.

File > Packages > Resolve Package Versions

You can also resolve packages from the command line when appropriate:

xcodebuild -resolvePackageDependencies -project MyApp.xcodeproj

Fix 4: Clear Derived Data

Corrupted or stale intermediate build files can break previews. Removing Derived Data can force Xcode to rebuild the required artifacts.

rm -rf ~/Library/Developer/Xcode/DerivedData/*

Afterward, reopen Xcode, use Product > Clean Build Folder, build the project again, and restart the Canvas.

Fix 5: Simplify preview dependencies

Preview code is more reliable when it uses mock or in-memory data rather than real services. Avoid requiring network calls, production databases, authentication state, or device-only resources just to construct the preview.

#Preview {
    ContentView(viewModel: .preview)
}

Fix 6: Check deployment targets and SDK compatibility

Make sure your app target, frameworks, and packages use compatible deployment targets and can all build with the SDK in your installed Xcode version. Large mismatches can cause the preview build to fail even when the visible SwiftUI code looks correct.

Important notes

Summary

When SwiftUI Preview reports “Failed to build the scheme”, first make sure the project builds normally. Then verify the selected scheme, Target Membership, package dependencies, Derived Data, preview-specific dependencies, and deployment settings. Restarting the Canvas and checking Preview diagnostics can help narrow down the remaining cause.