> For the complete documentation index, see [llms.txt](https://docs.sealights.io/knowledgebase/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sealights.io/knowledgebase/setup-and-configuration/troubleshooting-faq/qtest-integration/troubleshooting.md).

# Troubleshooting

## Connection Issues

### "timeout of 30000ms exceeded" or "failed to connect"

You are likely behind a corporate proxy. Set the proxy environment variable and retry:

{% tabs %}
{% tab title="Linux / macOS" %}

```bash
export HTTPS_PROXY=http://proxy.company.com:8080
npm run setup
```

{% endtab %}

{% tab title="Windows (PowerShell)" %}

```powershell
$env:HTTPS_PROXY = "http://proxy.company.com:8080"
npm run setup
```

{% endtab %}
{% endtabs %}

Verify that you can reach your qTest URL and `https://sealights.co` from a browser on the same machine. If the browser works but the tool times out, the proxy configuration is the cause.

See [Configuration — Proxy Configuration](/knowledgebase/setup-and-configuration/integrations/qtest-integration/configuration.md#proxy-configuration).

### "Connection refused" or "ECONNREFUSED"

Check that the `qTestUrl` in `config.json` is correct and accessible:

* It should end with a `/` (e.g. `https://company.qtestnet.com/`)
* Verify you can open the URL in a browser

***

## Authentication Issues

### "Invalid credentials" during setup

* Double-check your qTest username (email) and password
* Ensure your account is not locked out — try logging in through the browser
* If using SSO, ask your administrator for API credentials separate from your SSO login

### "Failed to validate token" or "Unauthorized"

Your SeaLights agent token may be invalid or expired:

* Re-generate the token from the SeaLights dashboard — see [Generating a Token](https://docs.sealights.io/knowledgebase/settings/token-access-and-management#token-list-and-token-creation-2)
* Re-run `npm run setup` to update `config.json` with the new token

### "Invalid bearer token" for qTest

The `auth.bearerToken` in `config.json` may have expired. Generate a new one from qTest or re-run `npm run setup` to re-authenticate.

***

## Report Issues

### "No test data found"

* Check the date range — try a longer window: `npm run report -- --days 30`
* Verify your qTest project has test executions in that period
* Confirm `defaultProject.name` in `config.json` matches the exact project name in qTest (case-sensitive)
* Run with debug output to see what the tool is fetching: `npm run report -- --debug`

### "Unknown user" warnings in report output

Some testers' qTest user IDs are not mapped to lab IDs. Run the mapping tool to assign them:

```bash
npm run manage-user-mapping
```

Select **"Fix pending mappings"** and assign a lab ID to each user showing `TODO-lab-id`. See [User Lab Mapping](/knowledgebase/setup-and-configuration/integrations/qtest-integration/concepts/user-lab-mapping.md).

### High number of unmapped tests

Tests in `output/unmapped/` were not resolved via Test Design mapping. This usually means:

* The test cases are in a folder not covered by `testDesignMapping`
* Test cases have been moved to a different folder in qTest — rebuild the cache: `npm run build-cache`
* The mapping is out of date — re-run `npm run setup` to update it

***

## Recommendations Issues

### Recommendations wizard shows no test stages

The wizard could not find test stages for the selected project. Possible causes:

* No test executions have been reported to SeaLights for this project — run `npm run report` first
* The `testDesignMapping` in `config.json` does not include any entries for this project
* The test stages in SeaLights and qTest do not match

### "Report too old" or "Report recency threshold not met"

SeaLights requires a recent report before it can provide recommendations. Run a fresh report:

```bash
npm run report -- --days 1
```

Then wait a few minutes and re-run the recommendations wizard.

### "⚠️ Mock mode enabled" in recommendations output

Your configuration has `recommendations.enableMockMode` set to `true`. This means recommendations are using mock data instead of the real SeaLights API. Update `config.json`:

```json
{
  "recommendations": {
    "enableMockMode": false
  }
}
```

### Skip status not applied in qTest

* Verify that the `skipStatusName` value in `config.json` exactly matches an existing execution status in qTest (case-sensitive)
* Confirm your qTest account has permission to update test execution statuses

***

## Configuration Issues

### "Invalid JSON" error on startup

`config.json` contains a syntax error. Validate it:

```bash
node -e "JSON.parse(require('fs').readFileSync('config.json','utf8'))"
```

Common causes: trailing comma, missing quotes, or unescaped special characters in passwords.

### "Missing required field" error

A required configuration field is absent from both `config.json` and environment variables. Check the error message for the missing field name, then add it to `config.json` or set the corresponding environment variable.

See [Configuration](/knowledgebase/setup-and-configuration/integrations/qtest-integration/configuration.md) for the full field reference.

***

## Getting More Information

Add `--debug` to any command for detailed diagnostic output:

```bash
npm run setup -- --debug
npm run report -- --debug
npm run recommendations -- --debug
```

Debug logs are also sent to SeaLights for support purposes. For cases where a specific test is missing from reports, see [Inspect Test — Diagnostic Tool](/knowledgebase/setup-and-configuration/troubleshooting-faq/qtest-integration/inspect-test.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.sealights.io/knowledgebase/setup-and-configuration/troubleshooting-faq/qtest-integration/troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.