> ## Documentation Index
> Fetch the complete documentation index at: https://momentic.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> The canonical docs host is https://momentic.ai/docs. Append .md to any page URL for clean Markdown. Fetch https://momentic.ai/docs/llms.txt for the page index and https://momentic.ai/docs/llms-full.txt for every page in one file.
> For an unattended setup, run `npx --yes @momentic/wizard@latest -y --platform web` (use `--platform ios` or `--platform android` for mobile). Never run an interactive command in a non-TTY shell.
> You cannot complete the browser sign-in yourself. Read the API key from the MOMENTIC_API_KEY environment variable, or ask the user to create one at https://app.momentic.ai/settings/api-keys and paste it back.
> Momentic's capability summary for agents is at https://momentic.ai/docs/skill.md. Install the skills with `npx momentic skills --yes` (or `npx momentic-mobile skills --yes` for mobile).
> Tests are YAML files in the user's repository. Use only the step names listed at https://momentic.ai/docs/reference/commands.md and the file structure at https://momentic.ai/docs/core-concepts/file-format.md. Do not invent step names, config keys, or CLI flags.
> Web tests run on Chromium, iOS tests on simulators, and Android tests on emulators. Physical devices are not supported.

# Common problems

> Recurring support problems, their causes, and the fixes.

Run `npx momentic doctor` (or `npx momentic-mobile doctor`) first. It reports
the CLI version, authentication, connectivity, browsers, and project config. If
your problem is not on this page, see [Get help](/docs/account/help).

## Setup

### `install-browsers` takes more than 10 minutes in CI

`chrome` pulls in more system packages than `chromium`, and a Node module cache
does not cover them. If your tests do not depend on branded Chrome, install
`chromium` only:

```bash theme={null}
npx momentic install-browsers chromium
```

To remove the install step from every job, build a runner image with the
browsers and their system packages preinstalled.

### Which Node.js version do I need?

Node.js 22.12.0 or later in the 22.x line, or 24.0.0 or later. Node.js 23 is not
supported. `momentic` 3.0 and `momentic-mobile` 1.0 dropped Node.js 20. See the
[v3 upgrade guide](/docs/get-started/upgrade-to-v3) and the
[mobile v1 upgrade guide](/docs/get-started/upgrade-to-mobile-v1).

### "Test has schema version X, which is newer than this version of the CLI supports"

A newer CLI than the one in CI saved the test. Each save writes the schema
version of the CLI that runs the editor, so `npx momentic@latest app` on one
laptop can break every pipeline that pins an older version. Pin one version in
`package.json`, start the editor from that install with `npx momentic app`, and
upgrade the pin and the test files in the same pull request.

## Authentication

### The CLI cannot find my API key

The CLI reads `--api-key`, then `MOMENTIC_API_KEY`, then `~/.momentic/auth.json`
from `momentic login`. Run
[`momentic whoami`](/docs/cli-reference/momentic/commands/whoami) to see which key it
found and which organization the key belongs to. In CI, set `MOMENTIC_API_KEY`
from your secret store. Create keys in the
[dashboard](https://app.momentic.ai/settings/api-keys).

### The login step fails on an OTP or MFA code

When parallel runs sign in with one email address, each run reads the other
runs' codes and the codes expire or fail. Give each run its own address with
plus addressing, for example `qa+{{ Date.now() }}@example.com`, or create the
user in an API request step at the start of the test.

Momentic reads codes from a Momentic inbox or an SMS number. See
[Email OTP](/docs/guides/auth/email-otp) and [SMS OTP](/docs/guides/auth/sms-otp). For an
authenticator app, use the TOTP secret with [otpauth](/docs/guides/auth/otpauth) or
turn off MFA for the test user. Keep passwords and TOTP secrets in
[environment variables](/docs/configuration/environment-variables#secrets), not in
test files.

### The cached login module passes, but the page is logged out

The module cache stores browser state after the module's last step. If that step
clicks **Sign in**, the stored state predates the redirect. End the module with
a check that passes only when the user is signed in, such as an element check on
the account menu. If the app's session is shorter than `defaultCacheTtl`, lower
the TTL. To drop a bad entry, change the cache key. The stored state has
cookies, `localStorage`, and IndexedDB, not `sessionStorage`; if your app keeps
its token in `sessionStorage`, do not cache the module. See
[Authentication modules](/docs/core-concepts/modules#authentication-modules).

### Cloudflare, a WAF, or bot detection blocks the run

Tests run on the machine that runs `momentic run`, so requests to your app come
from that machine's IP. Allowlist your CI runners, or give them a fixed egress
IP. For traffic that Momentic sends from its own infrastructure, see
[IP whitelist](/docs/core-concepts/authentication#ip-whitelist). Momentic does not
solve CAPTCHAs; turn them off for test traffic with a header or cookie your app
recognizes.

## Writing tests

### "Template fragment 'env.NAME' evaluated to undefined"

Nothing set the variable before this step read it, or the name differs. Check
spelling and case. Confirm the variable is set in `momentic.config.yaml`, the
environment, or an earlier step. A module parameter is visible inside that
module only. Names inside `{{ }}` are JavaScript identifiers, so `MY_VAR#1` is
invalid. See [Variables](/docs/core-concepts/variables).

### The AI cannot find an element inside an iframe

Steps do not look inside iframes by default. Set
`browser.autoExpandIframes: true` in `momentic.config.yaml`. If a recorded step
targets the iframe by URL and the URL changes on each run (payment providers do
this), remove the URL from the target or match it with a regular expression. See
[Page handling](/docs/configuration/browser#page-handling).

### A link opens a new tab and the next step fails

Steps keep acting on the original tab. Add a
[`switchTab`](/docs/reference/commands/switch-tab) step after the click. We
deprecated `browser.autoFollowNewTabs` because it races the page load. If the
new tab loads slowly, raise `browser.pageLoadTimeoutMs`. See
[Timeouts](/docs/configuration/browser#timeouts).

### A cookie banner, toast, or dialog breaks a step

For a banner that appears on some runs only, set the cookie or `localStorage`
value that hides it in the `browser` config. See
[Headers, storage, and identity](/docs/configuration/browser#headers-storage-and-identity).
For a toast that disappears before the check runs, use
[`assertVisually`](/docs/reference/commands/assert-visually) right after the action
that shows it. On Android, set `emulator.autoGrantPermissions: true` so
permission dialogs do not appear. See
[Mobile configuration](/docs/configuration/mobile).

### A step passes locally and fails in CI

Slow runners change timing. Open the **Resources** tab of the failed run. CPU
near 100% produces `Page.captureScreenshot timed out`,
`DOMStorage.enable timed out`, and missed elements. Lower `--parallel`, use a
larger runner, or shard the suite. Raise `browser.pageLoadTimeoutMs` for slow
environments. If the element description is the cause, see
[Finding elements](/docs/core-concepts/finding-elements). See
[Parallelism and sharding](/docs/running-tests/performance#parallelism-and-sharding).

## Results

### `results upload` or `results merge` exits with code 137

The runner killed the process for memory. Upgrade to the latest CLI first. If
the merge still fails, skip it: pass one `--run-group-id` to every shard with
`--upload-results`, so each shard uploads its own results and the dashboard
groups them. See
[Group independent invocations](/docs/running-tests/results#group-independent-invocations).

### "Upload failed: results path does not exist"

The run wrote to a different `--output-dir` than the one passed to
`results upload`, or the upload job runs on another runner without the artifact.
Upload from the job that ran the tests, or pass the results directory between
jobs as an artifact. See [Results](/docs/running-tests/results).

### Classification settings disappeared from the dashboard

**Classify on fail** and **Override CI exit code** moved to
`momentic.config.yaml`:

```yaml momentic.config.yaml theme={null}
ai:
  classification:
    enabled: true
    overrideExitCode: true
```

With `overrideExitCode: true`, failures the classifier routes to **heal** or
**warn** exit `0`. Omit it if you did not use the dashboard toggle. If you run
`momentic ai classify` in a separate job, start it after the upload finishes.
See [AI configuration](/docs/configuration/ai).

## Mobile

### The emulator does not start or disconnects

Close other Momentic sessions on the same machine, then run `adb emu kill` and
`adb disconnect` before you start `npx momentic-mobile app` again. Remote
Android emulators need a local `adb`; install platform-tools and set
`ANDROID_HOME`. See [Install adb](/docs/platforms/android/app-setup#install-adb). A
VPN or proxy that injects its own certificates also breaks the connection; turn
it off or allowlist `*.momentic.ai`.

If the error is `Could not find a driver for automationName 'UiAutomator2'`,
several Appium instances raced on the driver manifest. Lower `--parallel` and
retry.

If iOS works and Android does not, and nothing changed on your side, ask
[support](/docs/account/help) before you reinstall.

## Coding agents

### The MCP server does not start in VS Code, Cursor, or Claude

A server entry in a user-level config (Claude Desktop, Codex
`~/.codex/config.toml`) needs an absolute `--config` path, because the editor
does not start in your project directory. Project-level entries, which
`install-mcp` writes by default, can use a relative path. The editor process
also needs `MOMENTIC_API_KEY`; set it in the entry's `env` block or run
`momentic login`. Restart the editor after each config change.

`npx momentic install-mcp` writes a correct entry for each detected client. See
[MCP server](/docs/coding-agents/mcp-server).

### One editor, several `momentic.config.yaml` files

Each project needs its own server entry with its own `--config` path. Web and
mobile servers use the names `momentic` and `momentic-mobile`, so one config
file holds both. For two web projects, give each entry a different name.