SwiftUI previews failing or crashing is a frequent frustration. Here's a systematic way to diagnose and fix preview errors so your live canvas works again.
SwiftUI previews render your interface live in Xcode's canvas without launching the full app. When they work, they make UI iteration fast.
When they fail, you see messages like 'Preview crashed', 'Cannot preview in this file', or a canvas stuck on building. It is one of the most common SwiftUI annoyances.
Previews are essentially a special build that runs your view in isolation. That means anything that breaks a build, or anything your view depends on that is missing in isolation, can break the preview.
Understanding that mental model, that a preview is a mini build of just your view, makes the fixes far more logical.
Previews cannot run if the project does not compile. Before debugging the canvas, build the whole app with Command-B.
Fix any compiler errors first. A single error elsewhere in the module can stop previews even if the current file looks fine.
Pay attention to errors in shared code, models, or extensions your view relies on. The preview needs all of that to compile.
Only once the project builds cleanly should you spend time on preview-specific issues. This single step resolves a large share of preview failures.
Sometimes the preview is simply paused. Look for a Resume button in the canvas and click it, or use Option-Command-P to refresh the preview.
If the canvas is not visible at all, enable it from the Editor menu by turning on the Canvas option.
A refresh forces Xcode to rebuild the preview, which clears many transient glitches where the canvas got out of sync with your edits.
If resuming immediately fails again with an error, move on to checking what your view needs to render.
Many preview crashes happen because the view needs data that is not supplied in the preview itself.
If your view expects an environment object, a model, or initialization parameters, the preview must provide them. A view that reads an unset environment object will crash when previewed.
In your preview, inject sample data: pass mock values into the initializer and attach any required environment objects with the appropriate modifier.
Using realistic sample data also makes previews more useful, since you see the view rendered with content rather than empty placeholders.
Previews run in a constrained environment. Code that performs network calls, touches the file system, or depends on real device state can fail or behave oddly.
If your view or its initializer triggers heavy work or external dependencies, guard against it or inject mock implementations for previews.
A clean separation between view and data, where the view receives its data rather than fetching it, makes previews far more reliable.
When a preview crashes only because of a side effect, supplying a fake or in-memory version of that dependency usually fixes it.
Preview tooling can get into a bad state. When errors seem unrelated to your code, clear the caches.
Use Product > Clean Build Folder (Shift-Command-K), then try the preview again. This clears stale build artifacts that confuse the preview system.
If that does not help, quit and reopen Xcode. Restarting resets the preview process and resolves many otherwise inexplicable failures.
As a deeper step, you can clear derived data, which forces a full rebuild of the project and its indexes.
Previews are resource-intensive because they compile and run continuously as you edit.
On machines with limited RAM, or with many apps open, previews can time out or crash simply from pressure. Closing other heavy applications can help.
Keeping Xcode and macOS reasonably up to date matters too, since preview reliability has improved across releases and newer SDKs.
If previews are consistently unusable on older hardware, running the app in the Simulator with Command-R remains a dependable fallback while you iterate.
When a preview fails, Xcode usually offers a diagnostics button or a way to view the underlying error. Do not skip past it.
The preview system runs a build and then launches your view, so the error often contains a real compiler message or a runtime crash reason buried under the generic banner.
Expanding that diagnostic frequently reveals the exact line or the missing dependency, which turns a vague 'preview crashed' into an actionable fix.
Treat the preview error like any other crash log: find the root cause it names, address that, and the canvas usually comes back to life.
The most reliable way to avoid preview problems is to write views that are easy to preview in the first place. The key idea is dependency injection.
A view that receives its data through its initializer, rather than reaching out to a network client or a singleton, can always be previewed by passing in sample values.
Keeping side effects out of view initialization is just as important. If creating a view kicks off a network request, the preview inherits that fragility.
This same discipline pays off beyond previews. Views that take their inputs explicitly are easier to test, easier to reuse, and less likely to surprise you, so the effort improves your whole codebase.
It helps to remember what a preview is and is not. A preview renders a single view quickly, but it is not a full run of your application.
State that accumulates as a user navigates, deep links, background tasks, and complex flows are better exercised by actually running the app.
Use previews for what they excel at: tweaking layout, spacing, colors, and how a view looks across light and dark mode or different dynamic type sizes.
For anything involving real data flow, multiple screens, or system integration, run on the Simulator or a device. Knowing which tool fits which job saves you from forcing previews to do something they were never meant to.
Previews are a convenience, not a requirement. If one stubbornly refuses to work, you can still build and run your app normally.
Running in the Simulator or on a device always reflects the true behavior of your UI, so use it when previews are being uncooperative.
Meanwhile, structuring your views to receive data and avoid side effects pays off broadly. It makes previews, tests, and the app itself more robust.
Over time, the same habits that fix previews, clean builds, injected dependencies, and a compiling project, prevent most future preview headaches.
The most common causes are a project that doesn't compile, a view that needs data or environment objects not provided in the preview, or side effects like network calls. Fix the build first, then inject sample data.
Click Resume in the canvas or press Option-Command-P. If that fails, clean the build folder with Shift-Command-K and restart Xcode.
No. SwiftUI previews run on your Mac through Xcode and do not require a device or paid account. They do require the project to compile successfully.
Previews are resource-heavy. On limited hardware they may time out. You can always build and run in the Simulator or on a device with Command-R as a reliable alternative.