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 EAS Simulator.

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 commands remain hidden because the API is experimental.

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

EAS Simulator 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:

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.

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.

Unknown command: tap or Unknown command: click

The agent-device action is named press:

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
• --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 not valid with --build-id or --application-archive-url.

The remote device does not contain the app

This is expected when the session starts without --build-id, --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.

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

Android did not return a webPreviewUrl

Android browser preview is not currently supported. Use agent-device or Argent and collect screenshots or recordings instead.

The preview appears inside the simulator

The webPreviewUrl was opened as though it were an app URL. Open it in the desktop browser instead. It is a browser stream, not an application deep link.

Report feedback

EAS Simulator 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 EAS Simulator skill: