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:

Linux / macOS

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

Windows (PowerShell)

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.

"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

• 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:

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.

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:

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:

{
  "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:

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 for the full field reference.

---

Getting More Information

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

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.