Troubleshooting

Browser Won’t Launch

Symptom: browserType.launch: Executable doesn't exist or similar Playwright error.

Fix: Install the browser binary:

npx playwright install chromium

On Linux (CI environments), you may also need system dependencies:

npx playwright install chromium --with-deps

If you’re using Firefox or WebKit, install the corresponding browser:

npx playwright install firefox
npx playwright install webkit

Cloud Features Not Working

Symptom: save_suite, run, list, or other cloud tools return authentication errors.

Fix: Run the setup tool to authenticate:

Run setup

This opens a URL for the OAuth device code flow. After completing authentication, your API key is saved to ~/.fasttest/config.json.

If you already authenticated but it stopped working, your API key may have been rotated. Run setup again.

Session Expired or Invalid

Symptom: Tests that depend on a saved session fail with login redirects or 401 errors.

Fix: Sessions (cookies, localStorage) expire based on your app’s session policy. Re-save the session:

Log in to https://myapp.example.com and save the session as “admin”

This uses the browser_session tool with the login action, which opens a headed browser for you to complete the login flow manually.

Rate Limit Hit

Symptom: API requests return 429 Too Many Requests.

Fix: The API allows 60 requests per minute per API key. This is rarely hit during normal usage. If you’re scripting against the API, add backoff logic. A typical test run uses only a handful of API requests regardless of test count.

Tests Pass Locally but Fail in CI

Symptom: Tests work in your IDE but fail in GitHub Actions or other CI.

Common causes:

Missing environment variables — Check that all {{VAR_NAME}} placeholders have corresponding CI secrets. Use list(type='suites') or the dashboard to see required_variables for a suite.
Missing browser dependencies — On Ubuntu (GitHub Actions), use --with-deps:
Terminal window
```
npx playwright install chromium --with-deps
```
Timing differences — CI runners are slower than local machines. If tests have tight timing, increase wait timeouts in your test steps.
Different base URL — If your CI tests against a staging URL that differs from your local URL, pass --app-url to the CI runner.

Self-Healing Not Working

Symptom: Tests fail with selector errors even though self-healing should fix them.

Possible causes:

Not connected to cloud — Stored healing patterns require cloud authentication. Run setup to connect.
Element was removed, not renamed — Self-healing fixes broken selectors (element exists but selector changed). If the element was removed entirely, that’s a real failure — not healable.
Assertion failure — Self-healing is intentionally skipped for assertion failures. If the element is found but the text/value doesn’t match, that’s flagged as a real bug.

MCP Server Not Detected by IDE

Symptom: Your AI assistant doesn’t recognize FastTest tools.

Fixes by IDE:

Claude Code: Verify with claude mcp list. If missing, reinstall:
Terminal window
```
npx -y @fasttest-ai/qa-agent@latest install
```
Cursor: Check Settings → MCP for the fasttest entry. Restart Cursor after adding.
VS Code: Check .vscode/mcp.json or your user MCP settings. Restart VS Code.
Other IDEs: See the IDE Setup guide for your specific IDE.

npx Caching Stale Version

Symptom: You updated but old behavior persists.

Fix: Clear the npx cache and force the latest version:

npx -y @fasttest-ai/qa-agent@latest --help

The @latest tag in your MCP config ensures the newest version is always used. If you pinned a specific version, update it.

Headed Mode Not Opening Browser

Symptom: --headed flag is set but no browser window appears.

Possible causes:

SSH/headless environment — Headed mode requires a display. It won’t work over SSH or in containers without a display server.
Flag not passed correctly — Verify --headed is in the args array in your MCP config, not embedded in the command string.

Need More Help?

Check the GitHub Issues for known issues
Ask your AI assistant: “Check FastTest health” to verify connectivity
Review execution logs in the dashboard under your project’s execution history