> 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/advanced-features/lightweight-v8-coverage-mode/troubleshooting.md).

# Troubleshooting

Start by turning on debug logs. Most problems in [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) show up as a clear log message.

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

```bash
export NODE_DEBUG=sl
export SL_LOG_LEVEL=debug
```

{% endtab %}

{% tab title="PowerShell" %}

```powershell
$env:NODE_DEBUG = "sl"
$env:SL_LOG_LEVEL = "debug"
```

{% endtab %}
{% endtabs %}

To write the log to a file, use `NODE_DEBUG=sl-file` (default file `sl.node.log`). See [Troubleshooting → Turn on logs](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/troubleshooting.md#turn-on-logs).

## The agent falls back to NYC <a href="#the-agent-falls-back-to-nyc" id="the-agent-falls-back-to-nyc"></a>

**Log message:** `Lean coverage listener failed to start, falling back to NYC: <error>`

The lightweight listener could not start, so the test listener collects coverage with NYC instead. The service keeps running. The same warning appears in the [Agent Monitor](https://docs.sealights.io/knowledgebase/setup-and-configuration/monitoring/sealights-cockpit/agent-monitor.md).

**What to check:**

* `slnodejs` is 6.2.100 or later.
* The coverage folder (`NODE_V8_COVERAGE`, default `.sl-cov`) can be created and written.
* The `<error>` part of the message. Include it when you contact SeaLights support.

## Lightweight mode does not start at all <a href="#lightweight-mode-does-not-start" id="lightweight-mode-does-not-start"></a>

**Symptom:** the log shows `Running agent using NYC`, without lightweight messages.

**What to check:**

* `SL_useLeanCoverageListener` is set to `true`, with this exact case.
* It is set in the environment of the process that starts the agent: in a container, in the container's runtime environment, not only in the CI step that builds the image.

## No coverage appears <a href="#no-coverage-appears" id="no-coverage-appears"></a>

**Log messages:** `No active execution. Prevent scan of report - <file>`, or `No hits. Prevent sending of footprints`.

**What to check:**

* **Node.js version.** On Node.js 20.6.0 or earlier, the program runs inside the `slnodejs` process and no coverage is collected for it. Use a later version.
* **Open test stage.** Coverage is sent only while a test stage is open on the service's lab ID (or on its build session ID, when no lab ID is set). Coverage read while no test stage is open is dropped (`No active execution`).
* **Raw coverage.** The build was scanned with `--rawCoverage` (or SeaLights turned it on remotely).
* **Coverage files.** The coverage folder receives `coverage-*.json` files while the program runs. If files appear only when the program exits, `SL_enableChildProcessPatcher` is set to `false`; remove it.
* **Project root and ignore rules.** `No hits` means the coverage file had no functions under the project root that are not excluded. Check `--projectRoot` / `SL_projectRoot` and `.slignore`.
* **Timing.** Coverage usually appears on the dashboard a minute or two after the test stage closes.

## TypeScript: zero coverage with a compiled output folder <a href="#typescript-zero-coverage" id="typescript-zero-coverage"></a>

**Symptom:** you scan `dist` (or another output folder), run the service from the project root, and get 0% coverage without errors.

**Cause:** the agent reports paths relative to its project root (the working directory), for example `dist/app.js`, while the scan expects paths relative to the scanned folder, for example `app.js`.

**Fix:** set the runtime project root to the scanned folder: `--projectRoot dist` on `slnodejs run`, or `SL_projectRoot=dist` with the preload script. See [How to Use → TypeScript](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/advanced-features/lightweight-v8-coverage-mode/how-to-use.md#typescript).

## Some files are missing <a href="#some-files-are-missing" id="some-files-are-missing"></a>

**Log messages** (debug level): `File <file> not belong to projectRoot`, `File <file> denied due to ignore rules`.

* Files outside the project root are skipped. Use the same project root at runtime as at scan time.
* Files that match `.slignore` (in the working directory), and everything under the project root's `node_modules`, are skipped.
* The scanned files must be the files that run. If the build changes files after the scan, scan after that step.

## Coverage is missing from child processes <a href="#child-processes-or-workers" id="child-processes-or-workers"></a>

* Child processes write their coverage when they exit, unless `SL_enableChildProcessPatcher=true`. Coverage written at the very end of the run is not sent, so child processes that run until the end (for example Jest workers) need `SL_enableChildProcessPatcher=true`.
* The child process must inherit `NODE_V8_COVERAGE`. A process started with an explicit environment that drops it writes no coverage.

**Log message** if the agent could not hook into child processes: `Patching spawn didn't succeed. Reason: <error>`.

## Coverage is lost at the end of a run <a href="#coverage-lost-on-stop" id="coverage-lost-on-stop"></a>

When your program exits on its own, the coverage of its last cycle and coverage not sent yet are not sent. With `SIGKILL` or an out-of-memory kill, nothing is flushed. On `SIGTERM` or `SIGINT` to `slnodejs`, the listener starts sending what it holds.

* After the last test, keep the service running for one more cycle (`SL_COVERAGE_INTERVAL` plus `SL_footprintsSendIntervalSecs`, 20 seconds with the defaults) before you stop it.
* Close the test stage after that; coverage sent after the test stage closes is not counted.
* Stop the service with `SIGTERM`, not `SIGKILL`. In Kubernetes, keep `terminationGracePeriodSeconds` at 10 seconds or more.

See [How to Use → Shutdown](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/advanced-features/lightweight-v8-coverage-mode/how-to-use.md#shutdown).

## The program ignores its own `SIGTERM` handler <a href="#sigterm-handler" id="sigterm-handler"></a>

Expected in this mode: on `SIGTERM` or `SIGINT`, your program exits immediately with exit code `0`, and its own handlers for these signals do not run.

## Extra lines in the program output <a href="#extra-output" id="extra-output"></a>

Lines that start with `pid - <process id> :` (for example `pid - 4242 : Preloader initialization`) and `Failed to read config from file - sl.conf` come from the lightweight listener and are expected.

## Errors sending coverage <a href="#errors-sending-coverage" id="errors-sending-coverage"></a>

**Log message:** `Error while flushing footprints: <error>`

The listener could not reach SeaLights. Check that the service can reach the SeaLights server, directly or through `--proxy` / `SL_proxy`, and that the token is valid for that server. Behind a TLS-inspecting proxy, see [Troubleshooting → TLS and proxy](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/troubleshooting.md#tls-and-proxy-issues).

## The coverage folder keeps growing <a href="#coverage-folder-grows" id="coverage-folder-grows"></a>

Node.js writes coverage files to the coverage folder, and the agent does not delete them. On long-running environments, clean the folder between runs, or point `NODE_V8_COVERAGE` to a temporary volume.

A `.sl-cov-tmp` folder means debug logging is on. Set `SL_LOG_LEVEL` back to `info` and delete the folder.

## Contacting support <a href="#contacting-support" id="contacting-support"></a>

Send SeaLights support:

* The agent log with `SL_LOG_LEVEL=debug`. Remove the agent token from anything you send.
* The `.sl-cov-tmp` folder written at debug level.
* The `slnodejs` and Node.js versions.
* The scan command and the start command.


---

# 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/advanced-features/lightweight-v8-coverage-mode/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.
