> 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/sealights-agents-and-plugins/node.js-agent/troubleshooting.md).

# Troubleshooting

Turn on slnodejs logs, fix common problems (no data, missing coverage, TLS and proxy errors), and collect what SeaLights support needs.

Symptoms, causes and fixes for `slnodejs`, and how to collect logs for SeaLights support. For browser-side problems (agent not loading in the page, no browser footprints), see [Browser Agent → Troubleshooting](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent/troubleshooting.md).

## Turn on logs <a href="#turn-on-logs" id="turn-on-logs"></a>

By default the console shows only the agent's lifecycle messages. Logging is controlled by environment variables:

| Goal                    | Setting                                                                                                                                    |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Log to the console      | `NODE_DEBUG=sl` (or `sl-console`)                                                                                                          |
| Log to a file           | `NODE_DEBUG=sl-file`. The file is `SL_LOG_OUTPUT_FILE`, by default `sl.node.log` in the working directory. The directory must be writable. |
| Both                    | `NODE_DEBUG=sl,sl-file`                                                                                                                    |
| Change the level        | `SL_LOG_LEVEL`: `error`, `warn`, `info` (default), `http`, `verbose`, `debug` or `silly`                                                   |
| Turn off all agent logs | `SL_LOG_LEVEL=off`. This also turns off the TLS notices described below.                                                                   |

{% tabs %}
{% tab title="Bash" %}

```bash
NODE_DEBUG=sl,sl-file SL_LOG_LEVEL=debug npx slnodejs scan --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --scanDir dist --scmType git
```

{% endtab %}

{% tab title="PowerShell" %}

```powershell
$env:NODE_DEBUG = "sl,sl-file"
$env:SL_LOG_LEVEL = "debug"
npx slnodejs scan --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --scanDir dist --scmType git
```

{% endtab %}

{% tab title="CMD" %}

```bat
set NODE_DEBUG=sl,sl-file
set SL_LOG_LEVEL=debug
npx slnodejs scan --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --scanDir dist --scmType git
```

{% endtab %}
{% endtabs %}

Two more variables control what the agent sends to SeaLights:

* `SL_logSubmissionMode` (test listener): `0` sends no logs, `1` errors only, `2` all logs.
* `SL_DisableCockpitMessages=true` stops sending agent warnings and errors to the SeaLights dashboard.

## Collect logs for support <a href="#collect-logs-for-support" id="collect-logs-for-support"></a>

1. Run the failing command with `NODE_DEBUG=sl,sl-file` and `SL_LOG_LEVEL=debug`.
2. Send SeaLights support:
   * the log file (`sl.node.log` by default) and the console output;
   * the `slnodejs` version (`npm ls slnodejs --depth=0`) and the Node.js version (`node -v`);
   * the commands you ran (scan, start, test stage);
   * for scan problems, the `sl-dry-run-output` folder from [`dryRun`](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/advanced-features/dryrun-command-troubleshooting-and-validation.md).
3. Remove the agent token from anything you send. The agent masks the token in the configuration it logs, but your own command lines and scripts can contain it.

## A command fails but the pipeline passes <a href="#a-command-fails-but-the-pipeline-passes" id="a-command-fails-but-the-pipeline-passes"></a>

**Cause:** by default, a failing `slnodejs` command exits with status code 0, so that SeaLights never breaks a build.

**Fix:** add `--failOnError true` to the commands that must fail the pipeline (typically `config` and `scan`).

## Tests or the application run, but SeaLights reports nothing <a href="#tests-or-the-application-run-but-sealights-reports-nothing" id="tests-or-the-application-run-but-sealights-reports-nothing"></a>

**Symptom:** `slnodejs run` or `slnodejs mocha` prints `Sealights is disabled, running command without sealights`.

**Cause:** `slnodejs` could not start, most often because the token or the build session ID is missing or invalid. The tests or the program then run without SeaLights, so they are not blocked. The preload script behaves the same way.

**Fix:**

* Check that the token file and the build session ID file exist, at the paths you passed (`--tokenFile`, `--buildSessionIdFile`) or in the working directory.
* `run` and `nycReport` cannot find the build session from `--labId`: always pass a build session flag with them. See [Configuration → Build session ID](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/configuration.md#build-session-id).
* Check that the build session comes from `config` for the same build, and that the token belongs to the same SeaLights account.
* With the preload script, check the variable names: `SL_tokenFile`, `SL_buildSessionIdFile`, `SL_labId` (or `SL_TOKEN_FILE`, `SL_BUILD_SESSION_ID_FILE`, `SL_LAB_ID`). Other spellings are ignored.
* Turn on logs and look for the first error.

## Coverage is missing or low <a href="#coverage-is-missing-or-low" id="coverage-is-missing-or-low"></a>

| Cause                                                                                          | Fix                                                                                                                                                                                                                                                                                              |
| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| No test stage is open on the agent's lab while the tests run.                                  | Open the test stage with the same `--labId` the agent uses (without a lab ID, the build session ID is the lab ID). See [Labs and test stages](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/configuration.md#labs-and-test-stages). |
| The agent uses a different build session than the scan.                                        | Use the `buildSessionId` file from `config` of the same build for the scan and for the agent.                                                                                                                                                                                                    |
| File paths in coverage do not match the scanned paths.                                         | Use the same `--projectRoot` for the scan and the test listener (both default to the working directory).                                                                                                                                                                                         |
| The files that run are not the files that were scanned.                                        | Scan the build output that runs, after any post-build step that changes it.                                                                                                                                                                                                                      |
| Files are excluded by an ignore file or by the NYC configuration.                              | Check `.slignore` and the NYC `exclude` patterns. See [Configuration → Ignore files](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/configuration.md#ignore-files).                                                                  |
| The warning `NYC configuration detected in ... package.json` appears.                          | `include` or `exclude` rules in the `nyc` section of `package.json` limit the files NYC covers. Remove them, or align them with `.slignore`.                                                                                                                                                     |
| The error `Unable to create temporary folder needed for Nyc due to permission issues` appears. | NYC could not create its temporary folder in the working directory or in `/tmp/.nyc_output`, and the program ran without coverage. Run with write access to one of them.                                                                                                                         |
| The code is ES modules.                                                                        | Add `--es6Modules` to `scan` and to `run` / `mocha`. The preload script cannot collect NYC coverage from ES modules; use `slnodejs run --es6Modules`.                                                                                                                                            |
| Worker processes run the code.                                                                 | Set `SL_enableChildProcessPatcher=true`.                                                                                                                                                                                                                                                         |
| Server-side (SSR) Vue code: no coverage for methods in `.vue` `<script>` blocks.               | The test listener needs the `.vue` source files to place coverage on the right lines. Ship the `.vue` sources with the server.                                                                                                                                                                   |
| Coverage per test is missing; only per test stage.                                             | The application must receive the test identity: start the back end with `slnodejs run --httpServerColoring` (the preload script cannot), and use a SeaLights test framework plugin.                                                                                                              |

Also see [Missing or Insufficient Test Stage Coverage](https://docs.sealights.io/knowledgebase/setup-and-configuration/troubleshooting-faq/general/missing-or-insufficient-test-stage-coverage/test-stage-coverage-troubleshooting.md).

## TLS and proxy issues <a href="#tls-and-proxy-issues" id="tls-and-proxy-issues"></a>

`slnodejs` connects to SeaLights over HTTPS. Behind a proxy, set `--proxy` (or `SL_proxy` for the preload script and test listener).

TLS certificate verification is controlled by two environment variables, read by every command, the test listener and the preload script:

* `SL_TLS_VERIFY` (or `SL_tlsVerify`): `true`, `1` or `yes` verifies the TLS certificates of all SeaLights connections, including connections through a proxy. When it is not set, connections through a proxy are not verified.
* `SL_CA_FILE` (or `SL_caFile`): a PEM file with additional CA certificates, trusted on top of the Node.js defaults and the operating system store. It takes effect only when `SL_TLS_VERIFY` is on.

The TLS messages below start with `SeaLights:` and are written to the standard error stream or the log.

| Message                                                                                           | Meaning and fix                                                                                                                                                                                        |
| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `TLS certificate verification for <server> failed (...)`                                          | `SL_TLS_VERIFY` is on and the server certificate is not trusted, usually because a TLS-inspecting proxy replaces it. Set `SL_CA_FILE` to a PEM file with your corporate CA, or unset `SL_TLS_VERIFY`.  |
| `enabling SL_TLS_VERIFY would currently fail for <server> (...)`                                  | `SL_TLS_VERIFY` is off, and a test connection showed that turning it on would fail. Set `SL_CA_FILE` before you turn on `SL_TLS_VERIFY`.                                                               |
| `SL_CA_FILE is set but SL_TLS_VERIFY is not - certificates are not verified`                      | `SL_CA_FILE` has an effect only when `SL_TLS_VERIFY` is on.                                                                                                                                            |
| `SL_CA_FILE '<file>' contains no PEM certificates - ignoring it`, or `Cannot read SL_CA_FILE ...` | The CA file is not usable. Point `SL_CA_FILE` to a readable PEM file.                                                                                                                                  |
| `an https:// proxy is configured, so TLS verification stays disabled for the whole process`       | With an `https://` proxy and `SL_TLS_VERIFY` off, TLS verification is turned off for the whole process, including your application's own HTTPS calls. Set `SL_TLS_VERIFY=true` to verify certificates. |
| `sl-otel-agent is enabled with a proxy, so TLS verification stays disabled for the whole process` | With the SeaLights OpenTelemetry agent (`SL_useOtelAgent`), a proxy and `SL_TLS_VERIFY` off, TLS verification is turned off for the whole process. Set `SL_TLS_VERIFY=true` to verify certificates.    |

* The certificate of an `https://` proxy itself is trusted only through `NODE_EXTRA_CA_CERTS`.
* The operating system certificate store is used on Linux with all supported Node.js versions, and on macOS and Windows from Node.js 22.15. On older versions there, use `SL_CA_FILE`.

## Timeouts and retries <a href="#timeouts-and-retries" id="timeouts-and-retries"></a>

Every command and the test listener read these variables:

* `SL_httpTimeout`: timeout of one HTTP request to SeaLights, in milliseconds.
* `SL_httpMaxAttempts`: maximum attempts per HTTP request.
* `SL_httpAttemptInterval`: milliseconds between attempts.

## Scan problems <a href="#scan-problems" id="scan-problems"></a>

See [Scanning Your Application → Troubleshooting](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/scanning-your-application.md#troubleshooting) and [dryRun](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/advanced-features/dryrun-command-troubleshooting-and-validation.md).

## Memory and performance <a href="#memory-and-performance" id="memory-and-performance"></a>

* [NodeJS - JavaScript heap out of memory](https://docs.sealights.io/knowledgebase/setup-and-configuration/troubleshooting-faq/node-javascript/nodejs-javascript-heap-out-of-memory.md)
* [NodeJS: Memory Usage Explained](https://docs.sealights.io/knowledgebase/setup-and-configuration/troubleshooting-faq/node-javascript/nodejs-memory-usage-explained.md)
* For lower runtime overhead, use [Lightweight V8 Coverage Mode](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/advanced-features/lightweight-v8-coverage-mode.md).

## Deprecated settings <a href="#deprecated-settings" id="deprecated-settings"></a>

`slnodejs scan` warns when it finds a deprecated variable. `SL_httpMaxAttempts` replaces `SL_HttpMaxAttempts`, and `SL_httpAttemptInterval` replaces `SL_HttpAttemptInterval`. `SL_scmPrefix` is no longer supported and is ignored; use `--projectRoot`. `--useSlNode2` is deprecated and has no effect. The `jasmine`, `mochaPhantomjs`, `externalReport` and `installBabel` commands are removed.

## More articles <a href="#more-articles" id="more-articles"></a>

See the [Node/JavaScript troubleshooting articles](https://docs.sealights.io/knowledgebase/setup-and-configuration/troubleshooting-faq/node-javascript.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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/troubleshooting.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
