Skip to main content
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.

​
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:
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 and the mobile v1 upgrade guide.

​
”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 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.

​
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 and SMS OTP. For an authenticator app, use the TOTP secret with otpauth or turn off MFA for the test user. Keep passwords and TOTP secrets in environment variables, 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.

​
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. 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.

​
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. Steps keep acting on the original tab. Add a switchTab 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. 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. For a toast that disappears before the check runs, use assertVisually right after the action that shows it. On Android, set emulator.autoGrantPermissions: true so permission dialogs do not appear. See Mobile configuration.

​
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. See 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.

​
”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.

​
Classification settings disappeared from the dashboard

Classify on fail and Override CI exit code moved to momentic.config.yaml:
momentic.config.yaml
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.

​
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. 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 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.

​
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.