Skip to main content

Troubleshooting

Common issues and how to resolve them, grouped by area.

Generation (User Stories, Test Cases, Scripts, Test Data)​

Low-quality or too few results?

  • Add more detail to your project data — clear requirements, user flows, validation rules, and error scenarios produce better output. See Project Data.
  • For test cases, improve the underlying user stories and regenerate.

Generation won't start or button is disabled?

  • Confirm you have enough Flairs — check Settings → Usage.
  • A generation may already be in progress; wait for it to finish.

Notification never arrived?

  • Check that the relevant toggle is on under Settings → Notifications.
  • Browser notifications also require permission in your browser.

Test Execution​

Tests fail unexpectedly?

  • Verify the target URL is correct and reachable.
  • Confirm the application is running and responding.
  • Review the execution logs for the specific error.

Browser stream not showing?

  • The live browser view is available while a test is running; a recording is available after it completes.
  • Refresh the run view if the stream stalls.

Timeouts?

  • The application may be slow — increase the timeout in your execution preferences.
  • Confirm the target URL loads in a normal browser.

Testing Local Applications (Tunnels)​

Cloud browser can't reach localhost?

Tunnel URL not working?

  • Confirm the tunnel process is still running.
  • Re-copy the generated command and restart the tunnel.

Jira & Zephyr​

OAuth connection fails?

  • Ensure your Atlassian account has the required permissions.
  • Confirm the redirect URL in your Atlassian app matches TestFlair's callback URL.

API token not accepted?

  • Verify the token was generated from the correct account (Cloud) or instance (Self-Hosted) and that the email matches.

Import returns no results?

  • Check your JQL for syntax errors and confirm the project key is correct.

No "Sync Test Cases" / Zephyr option?

  • Zephyr export is a Beta feature and requires Zephyr Scale on the mapped Jira project. See Jira Zephyr.

AI field suggestions missing or weak?

  • Suggestions depend on issue content — well-structured descriptions yield better results.
  • Confirm your Flair balance is sufficient.

Test Runs​

All my cases show as Blocked?

  • Most often an engine mismatch. Check the run's engine on its Details tab against the engine the scripts were generated with. The other causes are a missing script and a script still generating. See Test Runs.

Progress stopped below 100%?

  • Blocked cases count toward the total but never settle, so a run containing them cannot reach 100%. Completion is signalled by the run's status, not by progress.

The run says Completed but everything failed?

  • That is a normal completed run reporting real failures. A run describes whether the work finished, not whether the application passed.

A case keeps coming back Flaky?

  • It passed only on retry. Look for timing assumptions in the script, or genuine instability in the application under test.

API Tests​

My OpenAPI import was rejected?

  • The specification must be valid OpenAPI. A spec that renders in a viewer may still be missing fields TestFlair needs.

Generation produced no API tests?

  • Generation works from the requirement text. Check that the user stories you selected describe behaviour the selected endpoints actually cover.

Requests are hitting the wrong host?

  • The base URL belongs to the spec version. Confirm you are working against the version you think you are.

TestFlair AI​

A slash command is greyed out?

  • That action isn't available yet. Ask for what you want in plain language instead — the slash menu is a shortcut, not the limit of what the assistant can do.

The assistant worked on the wrong project?

  • Mention the project with @ and ask again. A mentioned project takes priority over anything inferred from your wording.

The assistant can't see an item I asked about?

  • It works with your own permissions. If you cannot open something in the web app, it cannot either.

Connecting Your Editor (MCP)​

Tools stopped working, or I'm asked to sign in again?

"Not found" for an id I just used?

  • TestFlair does not distinguish does not exist from exists but is not visible to you. Check the id came from a list call made with the same account.

"Too many executions in flight"?

  • The cap applies per workspace and per user, so a colleague's run — or CI — may be holding the slots. Retry shortly.

See Connect Your Editor for the full list.

Access & Visibility​

I clicked a tab and got a "Coming Soon" page?

  • That feature is Beta and not enabled for your account. The Coming Soon page is what a gated feature shows — it is not an error, and nothing is broken. Contact your workspace admin or [email protected] for access.

A feature in these docs isn't in my app?

  • Several capabilities are Beta and gated per account: Test Runs, Test Plans, API Tests, TestFlair AI, the MCP server, Jira, Zephyr, GitLab, GitHub, user-story import, AI browser automation, AI bug generation, URL tunneling and referrals. They may not be enabled for your account — contact your workspace admin or [email protected].

Still stuck?​

Contact our team at [email protected].