Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Flutter and app store releases

The EAS build is for a device, so the iOS Simulator will not take it

ErrorAn iOS build from EAS cannot be installed on the iOS Simulator

Short answer

EAS builds iOS apps for physical devices unless the build profile says otherwise. A device build cannot be installed on the Simulator, and a simulator build cannot go on an iPhone. Add a separate profile with ios.simulator set to true, build with it, then install the result with eas build:run.

  • Applies to EAS CLI current, Expo SDK 5x, macOS with Xcode 26
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the profile you are building with and look for ios.simulator. If it is missing or false, the output is a device build.

    cat eas.json
  2. 2Match what you see, then jump to its fix

    1. 1The finished build cannot be installed on the Simulator, and EAS needed Apple Developer signing to make it.The build profile is not marked as a simulator buildFix
    2. 2The build finished, but the app is not on the Simulator home screen.The build was made correctly but is not installed the supported wayFix
    3. 3The app opens on a launcher or a development-server screen instead of your screens.A development build is installed but shows no appFix
    4. 4There is no iOS Simulator to install into.The machine is not a MacFix

What does the error look like?

  • An iOS build from EAS cannot be installed on the iOS Simulator
  • EAS asks for Apple Developer signing when you wanted a simulator build

Cause 1 of 4

The build profile is not marked as a simulator build

1Check

Open eas.json. The Expo docs say device builds use a profile where simulator is not true, and that an iOS device build can only be installed on iPhone devices, not on iOS Simulators.

grep -n -B2 -A4 simulator eas.json

2Fix

Add a profile that sets ios.simulator to true and keep your device profile as it is. The profile name is your own choice.

{
  "build": {
    "development": {
      "ios": { "simulator": false }
    },
    "development-simulator": {
      "ios": { "simulator": true }
    }
  }
}

3Verify

Build with the new profile. A simulator build does not need Apple signing.

eas build --platform ios --profile development-simulator

Confirmed by docs.expo.dev

Did this fix it?

Cause 2 of 4

The build was made correctly but is not installed the supported way

1Check

After a simulator build, the CLI offers to download and install it on the iOS Simulator. If you skipped that prompt, install a finished build later with eas build:run, which lists your available builds.

eas build:run -p ios

2Fix

Run eas build:run for iOS. Add --latest to take the newest build. Boot a Simulator first if none is open.

eas build:run -p ios --latest

3Verify

The app icon appears on the Simulator home screen and opens.

eas build:run -p ios --latest

Confirmed by docs.expo.dev

Did this fix it?

Cause 3 of 4

A development build is installed but shows no app

1Check

A development build needs the Expo dev server to load your JavaScript. The simulator guide says to start it with npx expo start once the build is installed.

npx expo start

2Fix

Keep the dev server running and connect the installed app to it from the Simulator.

npx expo start

3Verify

The app loads your project's first screen.

npx expo start

Confirmed by docs.expo.dev

Did this fix it?

Cause 4 of 4

The machine is not a Mac

1Check

The Expo docs state that iOS Simulators are available only on macOS.

uname -s

2Fix

Run simulator builds on a Mac. Without one, the other route is an iPhone device build, which needs a paid Apple Developer account for build signing.

eas build --platform ios --profile development

3Verify

On a Mac, the simulator build installs; for a device build, the app installs on the iPhone.

uname -s

Confirmed by docs.expo.dev

Did this fix it?

How do I stop it coming back?

  • Keep one profile for simulators and one for devices in eas.json, and name them so you cannot mix them up.
  • Remember the split: simulator builds run only on simulators and device builds run only on iPhones.
  • Use eas build:run instead of dragging files around by hand.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Related fixes

Mobile apps

App record creation fails because you lack permission

You cannot add a new app in App Store Connect as a Developer or limited user

Only the Account Holder, an Admin or an App Manager can create an app record, and Apple blocks it until the Account Holder has signed the latest agreement.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.