Skip to main content
For Mo, run qa doctor. For repository tests, run npx momentic doctor (web) or npx momentic-mobile doctor (mobile). See Get help if your problem is not on this page.

​
Mo sessions

​
Mo cannot reach the target

Check the exact URL from the brief, the account’s permissions, and deployment protection. See Give Mo access for sign-in and firewall settings. For an app on your machine or private network, keep its tunnel running while the session needs it.

​
qa report --require-idle says “Report not ready”

Mo or its sub-agents are still working. Follow the session with qa status and qa read, then retry the export. The flag checks readiness once. See Mo reports for partial snapshots and export options.

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

​
Node.js version

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.

​
A CLI command hangs

Record the exact command, the last terminal output, and how long it has been waiting. Run npx momentic doctor from the same project and shell. It checks the Node.js version, authentication, network connectivity, installed browsers, and missing browser system libraries. Follow the fixes in the report. For a browser installation, check the install-browsers requirements and the CI installation notes above. Node.js 24 is supported; a hang alone does not identify Node.js as the cause. If the command still hangs, contact support with the report and terminal output. If doctor also hangs, include the last section it printed. For a test run, use --reporter steps to log step progress and --timeout-minutes to set a run limit. See momentic run.

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

With a local browser, requests to your app come from the machine that runs momentic run. Allowlist your CI runners, or give them a fixed egress IP. With hosted browsers, requests can come from Momentic’s infrastructure or pass through your network tunnel. See IP whitelist. Momentic does not solve CAPTCHAs; turn them off for test traffic with a header or cookie your app recognizes.

​
Writing tests

​
Slow-motion execution (slowmo)

Set browser.slowMoMs to pause between web test steps. The value is in milliseconds, from 0 to 10000. The first executed step has no delay. Individual tests can override the project setting. Use the local editor to watch the test and inspect its steps. Remove the delay after debugging to avoid adding wait time to subsequent runs.

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

​
”Unknown Momentic platform error”

This category reports an internal Momentic error. Open the failed run and the failing step to read the full error and inspect its artifacts. The category alone does not identify the cause. Run the diagnostic command for your CLI listed at the top of this page. If the failure persists, contact support with the run URL or ID, the full error, the failing step, and the diagnostic output. Keep the failing run so support can inspect the original evidence.

​
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 concurrent sessions raced on the device-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.