Symptom: Xcode says it is building for iOS Simulator but linking an object file built for iOS, often naming arm64.
Fastest fix: check whether the named dependency includes an iOS Simulator slice; update it or rebuild it as a compatible XCFramework before changing architecture exclusions.

This guide is for you if a simulator build started failing after moving to Apple silicon, your project links a precompiled library or third-party SDK, or you maintain XCFrameworks for other developers. If your project uses only source dependencies and no binary artifacts, the source code and target settings are more likely places to investigate.

What the error tells you about the failed link

The wording points to a mismatch between the build destination and the binary being linked. “iOS Simulator” describes the destination platform Xcode is building for. “Built for iOS” identifies the platform of the object file or framework variant that the linker found. arm64 identifies a CPU architecture; it does not, by itself, tell you whether that binary is a simulator or device build.

That distinction matters on Apple silicon. An iOS Simulator build can use arm64, so seeing that architecture in the error does not prove that the simulator cannot use it. A device library built for iOS and a simulator library built for iOS Simulator can share the same CPU architecture while still being different platform builds. Apple’s technical note on resolving Apple silicon build errors explains why precompiled libraries need compatible architecture slices for the build destination.

Start with the named library, not a project-wide architecture setting. Record the dependency name, the target that fails, and the selected build destination. If one app target fails while another succeeds, compare the dependencies and configurations used by those targets before changing settings shared across the whole project.

A useful boundary test is to ask whether the error names a precompiled artifact. If it does, investigate that artifact’s platform support first. If the failure instead points to a project-built target, inspect that target’s SDK and platform settings. If Xcode reports a source compilation error rather than a link error, the missing slice diagnosis may not apply.

Why can’t an iOS device arm64 library link directly into a simulator build?

Matching CPU architecture is not enough. The linker needs an artifact built for the destination platform as well as an architecture it can use. A device-only arm64 binary is not transformed into a simulator binary merely because the simulator can also run arm64.

That is why changing an architecture exclusion can appear to affect the error without actually supplying the missing simulator artifact. The setting may change which architecture Xcode requests, but it cannot add a simulator platform variant to a device-only library. Apple’s XCFramework creation guidance describes packaging platform variants so a consumer can select the appropriate framework for its destination.

Check which platform slices the dependency actually contains

Inspect the dependency named in the linker output and identify how it is distributed. A vendor-provided XCFramework should contain variants that identify their supported platform and, where relevant, platform variant. A legacy framework or static library may instead be a single binary intended for only one destination.

Artifact or evidence What it tells you Decision
XCFramework contains an iOS device variant only The dependency may support a physical iPhone or iPad target but not the simulator destination Request or install a simulator-compatible release
XCFramework contains an iOS Simulator variant with a usable architecture The package appears to offer a candidate for the current simulator build Check that Xcode selects this variant and retest the target
A standalone library reports arm64, but its platform is unclear Architecture alone does not establish simulator compatibility Ask the supplier for platform details or a proper XCFramework
Project-built library comes from a device-only build configuration The project may be producing the wrong artifact for the consuming target Rebuild it for the simulator and package the platform variants separately

Do not treat a list of architectures as proof of platform support. A binary inspection tool may show that a file contains arm64, but that output alone does not establish that the file was built for iOS Simulator. Use the package structure, build provenance, platform metadata, and a real link attempt together. Apple’s documentation for creating a multi-platform binary framework bundle is the reference for packaging those variants.

For a third-party SDK, inspect the vendor’s current release artifact rather than relying on an old installation note or a cached copy in the project. Confirm the version, download source, and included platform variants. If the vendor supplies a newer XCFramework that supports the simulator destination, update the dependency and remove stale copies that could still be linked by the project.

What if a third-party SDK has no Simulator arm64 slice?

First ask the supplier for a release that includes an iOS Simulator variant compatible with Apple silicon. If the supplier ships only device binaries, there is no project setting that can convert that device slice into a simulator slice. If the supplier provides simulator support for a different architecture but not arm64, treat any workaround as a constrained, temporary test path and validate what it changes in your own build environment.

If a compatible release is not available, choose based on the dependency’s role. You might temporarily remove an optional SDK from a simulator-only test target, replace it with a source dependency if the supplier supports one, or use a different supported build destination while you wait for a corrected artifact. None of these options makes the missing simulator variant appear; each changes what you are building or testing.

Apple also documents distributing binary frameworks as Swift packages. That guidance is useful when you maintain a binary dependency yourself or need to assess how a supplier packages its framework. The important check remains the same: the package must offer a platform variant suitable for the destination selected in Xcode.

Choose a repair that matches the dependency source

The reliable fix depends on who produced the binary and how it enters your project. Use the comparison below to avoid treating every linker failure as an architecture-setting problem.

Repair path Fit for the problem Confidence rating Main trade-off
Update a vendor XCFramework The supplier has published a simulator-compatible variant High You must confirm the project is using the updated artifact
Rebuild a library you maintain for the required platforms You control the source and build process High You need to preserve and verify each intended platform variant
Exclude an architecture for a narrowly defined target The dependency genuinely lacks support for that architecture, and the workaround is validated Conditional It can hide a symptom while leaving other destinations unsupported
Keep linking a device-only binary into the simulator target No matching simulator variant is available Low The platform mismatch remains and the link can continue to fail

For a vendor dependency, prefer a release that explicitly supports the simulator destination. For a library built inside your project, produce a simulator build from the library’s source and package it with the device build as an XCFramework. Apple’s guide to building and running an app distinguishes simulator and physical-device destinations; use the destination you intend to support when validating the result.

If the binary is delivered through a package manager or another dependency mechanism, verify the resolved artifact rather than assuming that a package name guarantees platform coverage. A clean build can help distinguish a stale local artifact from the current package contents. It does not repair an incomplete package, so check the framework that the linker actually consumes.

Changing EXCLUDED_ARCHS does not add a missing simulator platform slice. Use it only when you have identified a specific architecture limitation, scoped the setting to the intended target and configuration, and checked that the resulting build still meets your requirements.

Can EXCLUDED_ARCHS fix an Xcode simulator architecture error?

Sometimes it can work around a narrowly defined architecture limitation, but it is not a general repair for a device-versus-simulator platform mismatch. If a dependency lacks an iOS Simulator variant, excluding arm64 does not turn its device arm64 binary into a simulator binary. It may instead make Xcode request a different architecture, change which dependencies are eligible, or cause another target to fail.

Before applying an exclusion, identify the exact dependency and the target where the failure occurs. Confirm that the dependency supports the architecture you intend to use and that the setting will not affect unrelated targets or configurations. Then test the specific simulator destination and every other destination your project must support. Apple’s Xcode build settings reference explains how build settings affect a target; use it to verify the scope and value of the setting rather than copying a project-wide workaround without review.

The trade-off is straightforward: an exclusion may be a short-term compatibility measure when the library supplier documents a limitation, but it should not replace obtaining or building the correct platform variant. If the build only succeeds after a broad exclusion, record that as an unresolved compatibility constraint, not as proof that the dependency is fully supported.

Validate the artifact and both build destinations

Use this sequence to isolate the problem and make the repair repeatable:

  • [ ] Capture the failure context. Save the full linker message, the dependency name, the failing target, and the selected destination. The short error summary may omit which artifact path Xcode tried to link.
  • [ ] Locate the exact artifact. Check the resolved dependency or framework path used by the failing target. Look for duplicate or outdated copies that could take precedence over a newer package.
  • [ ] Inspect platform support. Confirm that the artifact includes a variant for iOS Simulator, not only iOS device. Check architecture information too, but do not use it as a substitute for platform identification.
  • [ ] Select the appropriate repair. Update a supplier package when a compatible release exists. If you control the library, rebuild it for the required destinations and package the outputs as an XCFramework.
  • [ ] Remove stale build products and rebuild the simulator target. Confirm that the updated artifact is actually selected and that the linker error no longer names the old binary.
  • [ ] Build the physical-device target as a separate check. Confirm that the device destination still links the device variant. A successful simulator build alone does not establish that the device build remains valid.
  • [ ] Record the dependency version and artifact source. Keep the version, package origin, and supported destinations alongside the project’s build notes so a later dependency or toolchain update can be checked against the same expectations.

The checklist is deliberately destination-focused. A simulator build passing while the device build fails usually points to an incomplete or incorrectly selected device variant, a changed package resolution, or target-specific settings. Conversely, a device build passing while the simulator build fails is consistent with a device-only dependency, but you still need to inspect the artifact before settling on that diagnosis.

Do not mark the dependency compatible based only on a successful clean build. Confirm that Xcode linked the intended framework and that both destinations use the appropriate variants. For projects with multiple app targets, repeat the check for each target that consumes the binary; dependency resolution and build settings can differ between targets.

The most common diagnostic trap is to stop once the word arm64 appears in the message. That narrows the architecture involved, but not the platform of the artifact. A package that contains an arm64 device framework can still lack the simulator framework your build needs. Conversely, a simulator-compatible arm64 variant should not be excluded merely because a device library with the same architecture failed to link.

If you need a separate environment to reproduce the result, record the dependency version and destination with the build log, then rerun the same simulator and device checks on that environment. Keep this separate from the repair itself: changing machines can help identify environment-specific or stale-artifact issues, but it cannot fix an XCFramework that omits the required platform variant. You can review the SSHMac help center when planning access to a separate Mac environment.

Make the fix durable across dependency updates

Treat simulator support as an explicit property of each binary dependency, not an assumption attached to its name or architecture. When you upgrade a vendor SDK, check the updated package contents and rebuild the destinations that consume it. When you publish an internal XCFramework, document which platforms it contains and make that claim part of the handoff to the application team.

If the project has a temporary EXCLUDED_ARCHS setting, note which target needs it, why it exists, and what release or artifact change would let you remove it. Revisit the setting when the dependency changes. Otherwise, a workaround that once addressed a genuine limitation can persist unnoticed, affect a different target, and make a later failure harder to trace.

The decision is clear: if the linker names an iOS device binary during an iOS Simulator build, first obtain a simulator-compatible XCFramework or rebuild the library you control. Only consider an architecture exclusion when you have verified a specific architecture constraint and its scope. For a final cross-check, using a separate Mac or isolated build environment helps reveal whether the repair holds outside your everyday workspace. If you need that temporary test environment, SSHMac provides access to a Mac you can use to repeat the simulator and device validation; if you build on the same Mac continuously or need a physical device connection, your existing local setup may be the better fit. Explore SSHMac.