This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

Diagnose access, session lifecycle, controller, installation, preview, and Fast Refresh issues in Expo Simulators.

Expo Simulators is a limited-access preview. It is not included with paid or free plans and is currently available only to select partners. Join the waitlist if you are interested in trying it.

Command not found

Command simulator:start not found

The installed EAS CLI is too old. Install or update EAS CLI, then inspect the command:

The simulator:* commands appear in eas --help from EAS CLI 24.8.0. Earlier versions hide the commands from the help output.

simulator:start rejects a documented flag

Update to the latest version of EAS CLI, then compare the command with the installed help:

Access and project errors

Expo Simulators is not enabled for the account

Check before starting:

If available is false, do not retry simulator:start. Use a local simulator or emulator, or join the waitlist for access.

EAS CLI reports that a user account is required

Log in interactively or provide EXPO_TOKEN in a headless environment:

EAS CLI reports that the project is not linked

Run the command inside the Expo project and initialize EAS:

Device run session max duration must not exceed ... minutes for this account

The requested --max-duration-minutes value is larger than the limit for your plan. The limit is 40 minutes on the Free plan and 115 minutes on paid plans. Any plan can set a custom value up to its limit. Use a smaller value, or omit the flag to use the plan maximum. See How long an Expo Simulators session runs.

Session lifecycle problems

The session takes a long time to start

Boot time varies with device capacity. While the device is starting, poll the existing session:

The session is ready when the status is IN_PROGRESS and remoteConfig is present. If it reaches STOPPED or ERRORED, or the start command reports a terminal failure, start a new session. Starting a second session while the first is still booting does not speed up the process.

A non-interactive session did not stop automatically

--non-interactive returns after the controller is ready. It does not stop the session. Run:

Starting a session left the previous session running

simulator:start creates a new session by default, even when .env.eas-simulator contains another session ID. It replaces the local configuration, but it does not stop the previous remote session.

List active sessions and stop the old one explicitly:

Use --no-force when you want simulator:start to fail instead of creating a new session while the environment already contains an ID. Give every session a descriptive --name so it is easy to identify in the list.

The start command shows that the session is queued

The session waits for available concurrency on your account. Sessions use the same job concurrency as other EAS jobs, such as EAS Build. Queue time does not count toward the 15-minute startup timeout. Stop sessions that you do not need to free concurrency:

A browser preview session stopped while someone used it

Controller activity from agent-device, Argent, or Appium resets the idle timer. Browser preview activity does not. For sessions that a person controls in the browser preview, omit --max-idle-time-minutes and use --max-duration-minutes to limit them.

Controller and tunnel problems

Remote daemon is unavailable or the tunnel endpoint is offline

The controller tunnel has dropped or the remote VM has ended. A dropped controller invalidates the installed app state, accessibility references, and connection configuration.

Stop the session if it is still active, then start a fresh session and repeat install → open → drive. Do not repeatedly retry a controller command against the dead endpoint.

Screenshots show a local simulator instead of the remote device

If .env.eas-simulator has no connection details, agent-device can use a local simulator without an error. This can happen when another simulator:start command replaced the file. Confirm that eas simulator:get --json returns the session ID that the start command printed.

Run eas simulator:exec npx agent-device@latest open <app>. In a remote session, the Session state path starts with /home/expo/ on Android or /Users/expo/ on iOS. A path under your own home directory means that the agent controls a local device. See How EAS CLI and agents select an Expo Simulators session.

DEVICE_NOT_FOUND when you select a second device

The agent-device --device flag accepts a device name only. To select a device by its unique device identifier (UDID), use --udid <UDID> instead. To control a second device, also pass a separate --session <name>. See Use a second device in the same session. List the device names:

Argent returns 401 Unauthorized after argent link

argent link without --yes keeps the old token when the URL is already linked. Link again with --yes:

If your editor already runs argent mcp, restart the editor so that it uses the new link.

A controller action hangs

Some iOS snapshots and interactions can take tens of seconds. If an action times out, refresh the interactive accessibility tree before retrying:

The original action may have reached the device even when the response was delayed, and blindly retrying can perform it twice.

install requires an active session or an explicit device selector

Pass the platform:

Screenshot reports that there is no active session

Open an installed app before taking the screenshot:

App and build problems

Launch options require an application source

--launch-arg and --open-url apply to an application installed during session startup. Pass exactly one source with the command:

• --build-id <build-id> for an EAS Build
• --build-fingerprint <fingerprint-hash> for the most recent finished EAS Build with that fingerprint
• --application-archive-url <url> for a remote application archive
• --expo-go for the Expo Go version matching the project SDK

For a local .app or APK, start a blank session and install it through agent-device or another controller instead.

Expo Go cannot determine the SDK version

Run the command from an Expo project with a valid app config, or pass --sdk-version <version> together with --expo-go. The SDK override is valid only with --expo-go.

The remote device does not contain the app

This is expected when the session starts without --build-id, --build-fingerprint, --application-archive-url, or --expo-go. Install a local simulator or emulator build through the controller, or start a new session with an application source.

The screenshot shows old source code

A release build embeds JavaScript at build time. Rebuild it from the current source, confirm that an existing EAS Build has the matching fingerprint, or install a development build and connect it to Metro.

Changing source files does not update an already-installed release build.

A recording did not download

The recording can still be a session artifact. Get the session with its ID and download the file from artifacts[].downloadUrl. See Recover a recording that did not download.

Fast Refresh does not work

Confirm all of the following:

• The installed binary is a development build with expo-dev-client, not a release build
• Metro is running once, without another process occupying port 8081
• The development client is connected to the public Metro tunnel URL
• The simulator session and controller are still active

Use tunnel v2 in remote or headless agent environments:

If the first connection fails, reset the simulator session and Metro once, then repeat the documented development-build flow. Reconnecting a release build cannot enable Fast Refresh.

Browser preview problems

The session page does not show the device

The session page on expo.dev does not embed the preview. Select Open preview to open the browser preview in a new tab. Android support is still in development, so some features that work on iOS may not work on Android yet. If the Android preview does not respond to input, control the emulator with agent-device, Argent, or Appium.

The preview appears inside the simulator

A controller command opened the browser preview URL as an app URL on the remote device. Open the URL in a desktop browser instead. It is a browser stream, not an application deep link.

Network problems

--egress local is only supported with --platform ios

EAS CLI versions before 24.9.0 support local egress only on iOS. Update EAS CLI to use local egress with an Android session.

Local egress is not enabled for the account

Local egress is an experimental feature. Contact Expo to enable it for your account.

Requests fail after the egress client disconnects

In a local egress session, proxied requests fail while the egress client is disconnected. The client tries to connect again. Keep eas simulator:egress running for the life of the session. The session keeps running and consuming usage while the client is disconnected.

The app cannot reach a server on your computer through local egress

Local egress refuses local and private addresses unless you allow them. Start the session with --egress-allow <host:port> for each server, such as --egress-allow localhost:3000. See Network traffic and local egress in Expo Simulators.

Report feedback

Expo Simulators and its CLI are experimental. Include the EAS CLI version, session ID, platform, controller type, and failing command when reporting a problem.

For feedback about the official Expo Simulators skill: