# 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](https://docs.sealights.io/knowledgebase/setup-and-configuration/integrations/qtest-integration/configuration#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](https://docs.sealights.io/knowledgebase/setup-and-configuration/integrations/qtest-integration/concepts/user-lab-mapping).

### 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](https://docs.sealights.io/knowledgebase/setup-and-configuration/integrations/qtest-integration/configuration) 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](https://docs.sealights.io/knowledgebase/setup-and-configuration/troubleshooting-faq/qtest-integration/inspect-test).