# Troubleshooting

Source: https://docs.qualflare.com/docs/faq/troubleshooting · Last updated: 2026-11-14

Common issues and step-by-step solutions for Qualflare — authentication, CLI, web UI, test execution, and CI/CD integration problems.

This guide helps you resolve common issues with Qualflare, including authentication problems, CLI errors, web UI issues, test execution failures, and CI/CD integration problems.

For errors from the `qf` CLI and CI uploads, see [Troubleshoot qf and CI uploads](https://docs.qualflare.com/docs/cli/troubleshooting); each CLI question here has a short answer and a link to the full steps. For sign-in and account problems, see [Sign-in and account problems](https://docs.qualflare.com/docs/faq/sign-in-problems).

**Quick links:**

* [Authentication & Access Issues](https://docs.qualflare.com/docs/faq/troubleshooting#authentication--access-issues)
  * [API Key Not Working](https://docs.qualflare.com/docs/faq/troubleshooting#api-key-not-working)
  * [Workspace Access Denied](https://docs.qualflare.com/docs/faq/troubleshooting#workspace-access-denied)
  * [SSO Login Failures](https://docs.qualflare.com/docs/faq/troubleshooting#sso-login-failures)
  * [User Permissions Too Limited](https://docs.qualflare.com/docs/faq/troubleshooting#user-permissions-too-limited)
* [CLI Tool Issues](https://docs.qualflare.com/docs/faq/troubleshooting#cli-tool-issues)
  * [Installation Fails](https://docs.qualflare.com/docs/faq/troubleshooting#installation-fails)
  * [Upload Command Fails](https://docs.qualflare.com/docs/faq/troubleshooting#upload-command-fails)
  * [Format Not Detected](https://docs.qualflare.com/docs/faq/troubleshooting#format-not-detected)
  * [Timeout During Upload](https://docs.qualflare.com/docs/faq/troubleshooting#timeout-during-upload)
  * [Retry Failures](https://docs.qualflare.com/docs/faq/troubleshooting#retry-failures)
* [Web UI Issues](https://docs.qualflare.com/docs/faq/troubleshooting#web-ui-issues)
  * [Page Not Loading](https://docs.qualflare.com/docs/faq/troubleshooting#page-not-loading)
  * [Missing Data or Empty Lists](https://docs.qualflare.com/docs/faq/troubleshooting#missing-data-or-empty-lists)
  * [Navigation Problems](https://docs.qualflare.com/docs/faq/troubleshooting#navigation-problems)
  * [Browser Compatibility Issues](https://docs.qualflare.com/docs/faq/troubleshooting#browser-compatibility-issues)
* [Test Execution Issues](https://docs.qualflare.com/docs/faq/troubleshooting#test-execution-issues)
  * [Launch Creation Fails](https://docs.qualflare.com/docs/faq/troubleshooting#launch-creation-fails)
  * [Test Cases Not Running](https://docs.qualflare.com/docs/faq/troubleshooting#test-cases-not-running)
  * [Results Not Appearing](https://docs.qualflare.com/docs/faq/troubleshooting#results-not-appearing)
  * [Environment Mismatch](https://docs.qualflare.com/docs/faq/troubleshooting#environment-mismatch)
* [CI/CD Integration Issues](https://docs.qualflare.com/docs/faq/troubleshooting#cicd-integration-issues)
  * [No Token in CI](https://docs.qualflare.com/docs/faq/troubleshooting#api-key-not-found-error)
  * [Upload Fails with Timeout](https://docs.qualflare.com/docs/faq/troubleshooting#upload-fails-with-timeout)
  * [Branch/Commit Not Detected](https://docs.qualflare.com/docs/faq/troubleshooting#branchcommit-not-detected)
  * [Test Results Not Found](https://docs.qualflare.com/docs/faq/troubleshooting#test-results-not-found)
* [App Issues](https://docs.qualflare.com/docs/faq/troubleshooting#app-issues)
  * [Invitation Expired or Not Found](https://docs.qualflare.com/docs/faq/troubleshooting#invitation-expired-or-not-found)
  * [Two-Factor Setup Required at Sign-in](https://docs.qualflare.com/docs/faq/troubleshooting#two-factor-setup-required)
  * [Quo or the AI Filter Is Unavailable](https://docs.qualflare.com/docs/faq/troubleshooting#quo-or-ai-filter-unavailable)
  * [Import Failed](https://docs.qualflare.com/docs/faq/troubleshooting#import-failed)
  * [A New Version Is Available](https://docs.qualflare.com/docs/faq/troubleshooting#new-version-available)

***

## Authentication & Access Issues

### API Key Not Working

Qualflare calls these keys access tokens. A `401` with `invalid or expired access token` (exit code `3`) means the token expired or was revoked, or stopped working after its creator's account or the workspace's sign-in rules changed: create a new token and save it with `qf login <identifier> --force`. Full steps: [`invalid or expired access token` (exit code 3)](https://docs.qualflare.com/docs/cli/troubleshooting#api-key-not-working).

***

### Workspace Access Denied

When your account isn't a member of a workspace, Qualflare shows the **Workspace not found** page: `This workspace doesn't exist or you don't have access to it.` Or it takes you back to your workspaces with the message `You no longer have access to this workspace.` Check that you're signed in with the right email, then ask a workspace Maintainer or Owner to invite you; invite links expire after 24 hours. Full steps: [Workspace and project access](https://docs.qualflare.com/docs/faq/sign-in-problems#workspace-access).

***

### SSO Login Failures

When single sign-on fails, the sign-in page names the reason and what to do. If your email domain isn't verified for single sign-on with the workspace, only the workspace Owner can verify it, under **Verified Domains**; enter your work email address and select **Continue** to go to your identity provider when the page says `Your organization requires single sign-on for this account.` Full list: [Single sign-on](https://docs.qualflare.com/docs/faq/sign-in-problems#sso-sign-in-errors).

***

### User Permissions Too Limited

**Symptoms:**

* Cannot create projects
* Cannot run tests
* Cannot view certain features
* Error: "You don't have permission to do this."

**Possible causes:**

* Your workspace role is Viewer or Guest, and you hold no higher role in this project
* Your project role is lower than the action needs
* The page needs a workspace role, such as Owner for Plan & Billing

**Resolution steps:**

1. Check your role:
   * Open **Users** in the workspace sidebar
   * If you don't see **Users**, your workspace role is Guest: you can open only the projects you were invited to
   * Find your name and check the **Role** and **Project Access** columns

2. Request a role change:
   * Ask a workspace Maintainer or Owner to **Promote** you on the **Users** page, or a project Maintainer or Owner to promote you on the project's **Settings → Users** page
   * Promote moves one step at a time and stops at Maintainer

3. Understand role differences:
   * **Viewer**: Read-only access
   * **Editor**: Create and edit test cases, launches, and defects, and create projects
   * **Maintainer**: Everything an Editor can do, plus invite people and change roles
   * **Owner**: Everything, including Plan & Billing, Single Sign-On, and deleting the workspace
   * **Guest**: Only the projects you were invited to

See [Roles and permissions](https://docs.qualflare.com/docs/administration/roles-permissions) for how workspace and project roles combine.

***

## CLI Tool Issues

### CLI Installation Fails

`command not found: qf` means the directory that holds `qf` isn't on your `PATH`, or your shell hasn't picked up the change: install with Homebrew or npm, or move the release binary into a directory on your `PATH`, then open a new terminal. Full steps: [`command not found: qf` after you install it](https://docs.qualflare.com/docs/cli/troubleshooting#installation-fails).

***

### CLI Upload Command Fails

`file does not exist` means the path is wrong for the directory `qf` runs in, and `failed to parse file` means the file isn't in the format `qf` expected: check the path, then run `qf validate <file>`, which needs no login. Full steps: [`file does not exist`, `no files match pattern` or `failed to parse file`](https://docs.qualflare.com/docs/cli/troubleshooting#upload-command-fails).

***

### CLI Format Not Detected

`unsupported format` means the `--format` value isn't one that `qf list-formats` prints; for JUnit-style XML from TestNG, Maestro, XCTest, Espresso or PHPUnit, always pass that tool's `--format` value. Full steps: [`unsupported format`, or qf reads the wrong format](https://docs.qualflare.com/docs/cli/troubleshooting#format-not-detected).

***

### CLI Timeout During Upload

`collect` gives up after 30 seconds by default, retries included: raise the deadline with `--timeout 2m`, because `QF_TIMEOUT` only caps each single request. Full steps: [`context deadline exceeded` during an upload](https://docs.qualflare.com/docs/cli/troubleshooting#timeout-during-upload).

***

### CLI Retry Failures

`qf` retries `429`, `500`, `502`, `503` and `504` answers and network errors, 3 times by default; exit code `7` after the retries means the failure was temporary, so re-run the job. Full steps: [The upload still fails after retries (exit code 7)](https://docs.qualflare.com/docs/cli/troubleshooting#retry-failures).

***

## Web UI Issues

### Web UI Page Not Loading

**Symptoms:**

* Blank white page
* Spinning loader never stops
* Browser tab shows "Loading..." indefinitely

**Possible causes:**

* Browser compatibility issue
* JavaScript error
* Network connectivity problem
* Ad blocker or browser extension conflict

**Resolution steps:**

1. Try a private window, or another supported browser: the latest Chrome, Firefox, Safari or Edge.
2. Turn off ad blockers and privacy extensions for `app.qualflare.com`.
3. Clear site data for `qualflare.com`, then reload the page.
4. Check [status.qualflare.com](https://status.qualflare.com) for an incident. If there is none, contact support with the error from the browser console.

***

### Missing Data or Empty Lists

**Symptoms:**

* Test cases not showing
* Empty launch list
* Projects disappeared
* Dashboard shows "No data"

**Possible causes:**

* Incorrect workspace selected
* Filter or search applied
* Data not yet synced
* Permission issue

**Resolution steps:**

1. Verify workspace context:
   * Check the workspace name at the top of the page
   * Ensure correct workspace is selected

2. Clear filters:
   * Look for active filter chips
   * Click "Clear filters" button
   * Reset date range

3. Refresh the page:
   * Press F5 or Cmd+R (Mac)
   * Hard refresh: Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)

4. Check permissions:
   * Open **Users** in the workspace sidebar and check your role. Guests don't see this page
   * The **Projects** page lists only the projects you're a member of. Ask a workspace Maintainer or Owner to invite you to a missing project

5. Check browser console for errors:
   * Press F12
   * Look for API errors in Network tab (red status codes)

***

### Web UI Navigation Problems

**Symptoms:**

* Cannot click buttons or links
* Dropdown menus don't open
* Page transitions hang
* "Back" button doesn't work

**Possible causes:**

* JavaScript disabled or blocked
* Browser extension conflict
* Cached stale state
* Browser compatibility issue

**Resolution steps:**

1. Try a private window, or another supported browser: the latest Chrome, Firefox, Safari or Edge.
2. Turn off ad blockers and privacy extensions for `app.qualflare.com`.
3. Clear site data for `qualflare.com`, then reload the page.
4. Allow JavaScript for `app.qualflare.com`.

***

### Browser Compatibility Issues

**Symptoms:**

* Layout broken or misaligned
* Features not working
* CSS rendering problems
* Interactive elements unresponsive

**Possible causes:**

* Using an unsupported browser
* Browser version too old

**Resolution steps:**

1. Use a supported browser:
   * Qualflare supports the latest versions of Google Chrome, Mozilla Firefox, Apple Safari and Microsoft Edge

2. Update the browser to its latest version.

3. Try a different browser:
   * If the issue persists, try another supported browser

***

## Test Execution Issues

### Launch Creation Fails

**Symptoms:**

* Clicking **Start** in the **Start Launch** dialog on the **Launches** page shows an error
* **Next** stays disabled in the dialog

**Possible causes:**

* Your role on the project is below Editor
* No suite is selected, or the selected suites have no test cases
* **Environment** or **Language** is empty
* The project has no environments

**Resolution steps:**

1. Check permissions:
   * Starting a launch needs the Editor role or higher in the project
   * Viewers cannot create launches

2. Check the dialog:
   * Select at least one suite. **Next** stays disabled until you do. The selected suites must contain test cases, or **Start** fails.
   * Choose an **Environment** and a **Language**. Both are required. **Platform** defaults to Web, and **Branch**, **Milestone** and **Name** are optional.

3. Verify environments exist:
   * Every new project starts with four environments: `development`, `staging`, `production` and `qa`
   * If they're missing, open **Settings** → **Environments** in the project and click **Create Environment**

4. Check browser console:
   * Press F12
   * Look for red errors in Console tab

***

### Test Cases Not Running

**Symptoms:**

* A manual launch stays **Pending** in the **Launches** list
* A launch has fewer case runs than you expected

**Possible causes:**

* The manual run isn't finished. Qualflare doesn't run tests itself: it has no runners and no queue. A manual launch stays **Pending** until you finalize it in the Test Wizard.
* The suites you selected didn't contain the cases you expected. A manual launch includes every case in the suites you selected when you started it.
* For an automated launch, the upload had fewer results than expected. Qualflare records only the results your upload contains.

**Resolution steps:**

1. Continue the run:
   * On the **Launches** page, click the **Pending** launch to open it in the Test Wizard
   * Record a verdict for every case

2. Finalize the launch:
   * When every case has a verdict, the wizard shows "Run complete." Click **Finalize Launch**
   * The launch leaves **Pending** and shows its result

3. Check what was uploaded:
   * For an automated launch, run the same `collect` command with `--dry-run --output json`. It parses the files and prints the report `qf` would send, without uploading:
   ```bash
   qf myapp collect results.xml --dry-run --output json
   ```

***

### Results Not Appearing

**Symptoms:**

* Your CI job ran, but no new launch appears on the **Launches** page
* A launch you expected is missing from the list

**Possible causes:**

* The upload failed, so Qualflare never created the launch
* The results went to another project. A launch always goes to the project of the access token that uploaded it.
* A filter on the **Launches** page hides the launch
* The page shows data from before the upload

**Resolution steps:**

1. Check the upload step:
   * Look at the output of the `qf … collect` step in your CI log
   * Exit code `0` means the launch was created. Any other code means the upload failed, and the message says why. See [Common Error Messages](https://docs.qualflare.com/docs/faq/troubleshooting#common-error-messages).

2. Check the project:
   * The launch lands in the project the access token belongs to
   * Open that project, then **Launches**

3. Check filters:
   * Clear the **Filter launches...** bar
   * Check the **Environment** filter in particular

4. Refresh the page:
   * Press F5 or Cmd+R (Mac)
   * Hard refresh: Ctrl+Shift+R (Windows)

5. Check the launch status:
   * A finished launch shows **Passed**, **Failed**, **Error** or **Skipped**
   * An automated launch whose results include pending tests but no failed or errored ones shows **Pending**
   * A manual launch shows **Pending** until you click **Finalize Launch** in the Test Wizard. See [Test Cases Not Running](https://docs.qualflare.com/docs/faq/troubleshooting#test-cases-not-running).

***

### Environment Mismatch

An upload fails with `environment "staging" does not exist in this project (status: 400)` when no environment in the project has that Identifier: pass an Identifier from **Settings** → **Environments** (new projects have `development`, `staging`, `production` and `qa`), or create it first. Without `--environment` or `QF_ENVIRONMENT`, `qf` uses the environment a native reporter recorded, or `development`. Full steps: [`environment "staging" does not exist in this project`](https://docs.qualflare.com/docs/cli/troubleshooting#environment-mismatch).

***

## CI/CD Integration Issues

### No Token in CI

`token cannot be empty` means `qf login` found no token in `QF_TOKEN` or on standard input, and `no identifier "ci" configured` means the job ran `collect` without logging in: expose the secret to the job as `QF_TOKEN`, and run `qf login ci --force` in the same job before `qf ci collect`. Full steps: [`token cannot be empty` or `no identifier "ci" configured` in CI](https://docs.qualflare.com/docs/cli/troubleshooting#api-key-not-found-error).

***

### CI/CD Upload Fails with Timeout

Raise the overall upload deadline with `--timeout` (default `30s`), for example `qf ci collect results.xml --timeout 2m`, and check that the job can reach `https://api.qualflare.com`. Full steps: [The upload times out in CI](https://docs.qualflare.com/docs/cli/troubleshooting#upload-fails-with-timeout).

***

### CI/CD Branch/Commit Not Detected

`qf` takes the branch from `QF_BRANCH`, `GIT_BRANCH`, `GITHUB_REF_NAME`, `CI_COMMIT_REF_NAME` or `BITBUCKET_BRANCH`, then from the local git checkout, and a detached HEAD has none: set `QF_BRANCH` and `QF_COMMIT`, or pass `--branch` and `--commit`. Full steps: [The launch has no branch or commit](https://docs.qualflare.com/docs/cli/troubleshooting#branchcommit-not-detected).

***

### CI/CD Test Results Not Found

`file does not exist` in CI means the job looks for the report in the wrong place, or another job wrote it: check the working directory, use an absolute path, and pass the file between jobs as a CI artifact. Full steps: [The results file isn't found in CI](https://docs.qualflare.com/docs/cli/troubleshooting#test-results-not-found).

***

## App Issues

### Invitation Expired or Not Found

An invitation that has expired, or that was accepted, revoked or replaced by a resend, opens the **Invitation Not Found** page: `This invitation could not be found or is no longer available.` Invite links expire after 24 hours, so use the newest invitation email, or ask a workspace Maintainer or Owner to invite you again. Full steps: [Troubleshoot invitations](https://docs.qualflare.com/docs/administration/users#troubleshoot).

***

### Two-Factor Setup Required at Sign-in

When a workspace you belong to requires two-factor authentication and your account has no second factor, you set one up the next time you sign in, before you can get in. Full steps and messages: [Two-factor authentication](https://docs.qualflare.com/docs/faq/sign-in-problems#two-factor-authentication).

***

### Quo or the AI Filter Is Unavailable

`AI features are disabled for this project` means **Enable AI Features** is off under **Project Settings** > **AI Features**, so Quo and the AI filter refuse requests in that project. When the workspace has used its monthly Quo messages, Quo says `You've used all <n> of this month's Quo messages. Upgrade your plan to keep going.` Full steps: [Quo error messages](https://docs.qualflare.com/docs/ai/quo#error-messages) and [What stops when AI is off](https://docs.qualflare.com/docs/ai/limits#when-ai-is-off).

***

### Import Failed

When an import can't finish, project members get the notification `Import failed: <file name>` with the reason, such as a file that isn't an export of the source you picked, or one over an import limit. Full steps: [Troubleshoot imports](https://docs.qualflare.com/docs/test-management/import-export#troubleshoot).

***

### A New Version Is Available

When a newer version of Qualflare was released after you opened the app, it shows `A new version is available` and `Reload the page to get the latest updates.` Click **Reload** in the message, or reload the page. For what changed, see [What's new](https://docs.qualflare.com/docs/faq/whats-new).

***

## Additional Resources

### Getting Help

If you're still experiencing issues after trying these troubleshooting steps:

1. **Check the documentation:**
   * [Qualflare CLI Tool](https://docs.qualflare.com/docs/cli) - Full command reference
   * [Quickstart](https://docs.qualflare.com/docs/get-started) - Your first upload
   * [FAQ](https://docs.qualflare.com/docs/faq) - Common questions

2. **Contact support:**
   * In-app chat: when you're signed in, click the chat button in the app. It needs **Functional** cookies.
   * Email: [support@qualflare.com](mailto:support@qualflare.com)
   * Include: error messages, screenshots, steps to reproduce
   * See [Contact support](https://docs.qualflare.com/docs/faq/getting-help) for what else to include

3. **Check service status:**
   * [status.qualflare.com](https://status.qualflare.com) shows current incidents

### Debugging Tips

**Enable verbose logging:**

```bash
qf myapp collect results.xml --verbose
```

**Log the full HTTP request and response (the token is redacted):**

```bash
qf myapp collect results.xml --debug
```

**Use dry run to test:**

```bash
qf myapp collect results.xml --dry-run --output json
```

**Check browser console:**

* Press F12 or Cmd+Option+I (Mac)
* Look for red errors in Console tab
* Check Network tab for failed API requests

**Include in support requests:**

* Error messages (exact text)
* Steps to reproduce
* Browser/CLI version
* Screenshots
* Configuration files (sanitize sensitive data)

### Common Error Messages

`qf` exits with `0` on success, `1` for a local or request error, `3` for an invalid or expired token, `4` when access is denied or a plan limit is reached, `5` when something isn't found and `7` for a rate limit or temporary server error (`429` or `5xx`). Errors from the API end with `[request_id: …]`, which support can trace. Full steps: [Exit codes](https://docs.qualflare.com/docs/cli/troubleshooting#exit-codes).
