Troubleshooting

Installation returns npm 404Copy Anchor Link

Neither package is published to npm yet. Follow the source installation instead of bare package-name installs. Install the app's own Expo dependencies before capture; Snapbot uses <appDirectory>/node_modules/.bin/expo.

Configuration or output rejectedCopy Anchor Link

Check required fields and limits. All paths use the project root, even when the JSON file is in another directory. Choose a new or empty output directory. If a lock remains after interruption, confirm there is no capture process still using it before manual cleanup.

Setup remains pending or shows an errorCopy Anchor Link

The build's apiEnvironment must match the requested value. Await theme/session setup and return true or void; returning false intentionally remains pending. isAuthenticating does not itself mark setup ready. Ensure parent routing and auth guards let /snapbot render. A static setup error can be visually stable, so inspect the visible UI and app logs.

Build or simulator problemsCopy Anchor Link

Use an installed runtime and device type. If duplicate simulator names exist, inspect the UDIDs in the diagnostic before removing an unwanted device. Check the app bundle identifier, Xcode scheme/workspace, and .app product name. Ensure the configured Metro port is unused. Native build and JavaScript bundle diagnostics are retained in run.log after output initialization.

• First-open confirmation: after installing the app, Snapbot automatically approves its configured URL scheme for CoreSimulator deep links. This avoids the iOS “Open in this app?” prompt on new simulators and newly captured apps, while preserving approvals for other apps. If approval cannot be written, the run stops with a specific error before waiting for the JavaScript bundle.
• Expo developer overlays: Snapbot starts the app with Expo's developer welcome screen, automatic developer menu, and floating developer button disabled for that process. No manual first-run setup is needed, and the app's saved developer preferences are unchanged.
• Xcode 27 has no separate Simulator app: open simulators from Xcode's Device Manager instead.
• Captures freeze for minutes at a time: simctl io screenshot blocks while the Mac sleeps. Keep it awake, for example with caffeinate -dims pnpm capture --project-root /absolute/path/to/app --config snapbot.json --output snapbot-output/awake-run from the Snapbot checkout.
• Every capture shows the same screen: an overlay stayed on top, such as a red React error screen or a system passcode prompt. Find the first capture where it appears and check the Metro errors in run.log.

Timeout or identical-frame warningsCopy Anchor Link

A timeout saves the last frame and normally exits zero. optional does not suppress navigation failures or change stability rules. Inspect animations, spinners, account data, and overlays before increasing timing limits. Use the post-run acceptance check if warnings should fail your workflow. A stable image alone cannot tell you whether the correct screen opened or login succeeded.