> Fixing SwiftUI Previews That Won't Load

SwiftUI previews are supposed to make development faster, but when they stop working, they can waste more time than they save. The preview canvas shows a vague error, you click "Diagnostics," and you're presented with a wall of text that doesn't obviously point to the problem. I've lost enough hours to broken previews that I now have a mental checklist I run through when they fail.

The Quick Fixes

Before diving into diagnostics, try these in order. They fix the issue more often than you'd expect.

Clean the build folder. Press ⇧⌘K or go to Product → Clean Build Folder. Stale build artifacts cause more preview failures than almost anything else.

Restart the preview. Click the "Resume" button or press ⌥⌘P. Sometimes previews just need a nudge.

Delete derived data. Open Finder and navigate to ~/Library/Developer/Xcode/DerivedData, then delete the folder for your project (or the entire contents if you're feeling thorough). This forces Xcode to rebuild everything from scratch.

If none of those work, it's time to look at the actual error.

Reading the Diagnostics

When a preview fails, the canvas shows a "Diagnostics" button. Click it to see the build log. The useful information is usually near the bottom—scroll past the compilation commands to find the actual error message.

Common patterns to look for:

"Cannot find type 'X' in scope" means your preview is referencing something that isn't available. This often happens when you move a file to a different target or rename a type.

"Failed to launch" or "Timed out waiting" suggests a runtime crash. Your preview code is compiling but crashing when it runs—usually due to force-unwrapping nil, missing resources, or infinite loops.

"Compiling failed" with no obvious error usually means a file elsewhere in your project has an error. Fix any build errors first, even in files unrelated to your preview.

Previews Crash at Runtime

If your preview compiles but crashes, the issue is in code that executes when the preview runs. The most common culprits:

Force-unwrapped optionals. If your view expects data from a network call or database that doesn't exist in previews, it crashes. Create mock data for your previews:

#Preview {
    ProfileView(user: User.mockUser)
}

extension User {
    static let mockUser = User(name: "Jane", email: "jane@example.com")
}

Missing resources. If your view loads an image or file that doesn't exist, previews crash. Ensure any resources referenced in preview code are included in your target.

Environment dependencies. Views that require specific environment values or objects fail if those aren't provided:

#Preview {
    ContentView()
        .environment(AppState())
        .environment(\.managedObjectContext, PersistenceController.preview.container.viewContext)
}

App lifecycle code. If your view's initializer triggers code that only works in the context of a running app (like accessing UIApplication.shared), wrap it in a check:

if ProcessInfo.processInfo.environment["XCODE_RUNNING_FOR_PREVIEWS"] != "1" {
    // Code that shouldn't run in previews
}

Previews Spin Forever

When the preview shows a loading spinner that never resolves, it's usually one of these:

Infinite loop in body. Double-check any computed properties or methods called during view rendering. An accidental recursion or endless loop will hang previews.

Heavy computation. If your view does significant work during initialization, previews may time out. Move expensive operations to .task or provide lightweight preview-specific data.

Async code that never completes. If you're awaiting something that requires the network or a running app to complete, previews will wait forever. Use mock data or detect the preview environment and return immediately.

Module and Target Issues

Preview failures often relate to how your project is structured.

If you're working in a Swift Package or framework, previews need your development target (usually an app) to provide the necessary runtime environment. Make sure you have an app target selected in the Xcode scheme selector, not just the package.

If your view is in one module but references types from another, all those modules need to build successfully for previews to work. A compile error in a dependency breaks previews in the dependent module.

For views in packages, adding preview content to the package's test target sometimes helps:

// In your package's test target
@testable import MyFeature

#Preview {
    FeatureView()
}

Reset Everything

When nothing else works, the nuclear option is resetting Xcode's caches completely:

1. Quit Xcode
2. Delete ~/Library/Developer/Xcode/DerivedData
3. Delete ~/Library/Caches/com.apple.dt.Xcode
4. Restart your Mac (yes, really—this clears some caches that survive a normal restart)
5. Open Xcode and build your project

This fixes strange state corruption that occasionally happens, especially after Xcode updates.

Preventing Future Issues

A few practices reduce preview headaches:

Keep preview code simple. Complex preview setups are more likely to break and harder to debug.

Use the preview provider's static nature to your advantage. Since previews are built ahead of time, design your views to accept injected dependencies rather than reaching out to global state.

Fix build warnings. Warnings sometimes indicate issues that escalate to preview failures.

When you add new dependencies to your app, test that previews still work before moving on. Catching issues early is easier than debugging them later when you've forgotten what changed.

Previews are invaluable when they work, and that's most of the time. Having a systematic approach to fixing them when they break keeps them from becoming a productivity drain.