Troubleshooting
Common issues and step-by-step solutions for Qualflare — authentication, CLI, web UI, test execution, and CI/CD integration problems.
Last updated
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; 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.
Quick links:
- Authentication & Access Issues
- CLI Tool Issues
- Web UI Issues
- Test Execution Issues
- CI/CD Integration Issues
- App Issues
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).
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.
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.
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:
-
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
-
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
-
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 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.
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.
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.
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.
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).
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:
- Try a private window, or another supported browser: the latest Chrome, Firefox, Safari or Edge.
- Turn off ad blockers and privacy extensions for
app.qualflare.com. - Clear site data for
qualflare.com, then reload the page. - Check 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:
-
Verify workspace context:
- Check the workspace name at the top of the page
- Ensure correct workspace is selected
-
Clear filters:
- Look for active filter chips
- Click "Clear filters" button
- Reset date range
-
Refresh the page:
- Press F5 or Cmd+R (Mac)
- Hard refresh: Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)
-
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
-
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:
- Try a private window, or another supported browser: the latest Chrome, Firefox, Safari or Edge.
- Turn off ad blockers and privacy extensions for
app.qualflare.com. - Clear site data for
qualflare.com, then reload the page. - 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:
-
Use a supported browser:
- Qualflare supports the latest versions of Google Chrome, Mozilla Firefox, Apple Safari and Microsoft Edge
-
Update the browser to its latest version.
-
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:
-
Check permissions:
- Starting a launch needs the Editor role or higher in the project
- Viewers cannot create launches
-
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.
-
Verify environments exist:
- Every new project starts with four environments:
development,staging,productionandqa - If they're missing, open Settings → Environments in the project and click Create Environment
- Every new project starts with four environments:
-
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:
-
Continue the run:
- On the Launches page, click the Pending launch to open it in the Test Wizard
- Record a verdict for every case
-
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
-
Check what was uploaded:
- For an automated launch, run the same
collectcommand with--dry-run --output json. It parses the files and prints the reportqfwould send, without uploading:
qf myapp collect results.xml --dry-run --output json - For an automated launch, run the same
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:
-
Check the upload step:
- Look at the output of the
qf … collectstep in your CI log - Exit code
0means the launch was created. Any other code means the upload failed, and the message says why. See Common Error Messages.
- Look at the output of the
-
Check the project:
- The launch lands in the project the access token belongs to
- Open that project, then Launches
-
Check filters:
- Clear the Filter launches... bar
- Check the Environment filter in particular
-
Refresh the page:
- Press F5 or Cmd+R (Mac)
- Hard refresh: Ctrl+Shift+R (Windows)
-
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.
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.
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.
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.
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.
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.
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.
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.
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 and What stops 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.
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.
Additional Resources
Getting Help
If you're still experiencing issues after trying these troubleshooting steps:
-
Check the documentation:
- Qualflare CLI Tool - Full command reference
- Quickstart - Your first upload
- FAQ - Common questions
-
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
- Include: error messages, screenshots, steps to reproduce
- See Contact support for what else to include
-
Check service status:
- status.qualflare.com shows current incidents
Debugging Tips
Enable verbose logging:
qf myapp collect results.xml --verboseLog the full HTTP request and response (the token is redacted):
qf myapp collect results.xml --debugUse dry run to test:
qf myapp collect results.xml --dry-run --output jsonCheck 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.
Frequently Asked Questions
Answers to common Qualflare questions about getting started, features and concepts, the web UI, the qf CLI, account and billing, and technical details.
Sign-in and account problems
Fix Qualflare sign-in problems: single sign-on errors, two-factor setup at sign-in, locked or deactivated accounts and access errors, with each exact message.