> 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/dryrun-command-troubleshooting-and-validation.md).

# dryRun Command: Troubleshooting and Validation

Use `dryRun` to validate your `slnodejs` setup locally before you spend time on CI runs.

It helps you confirm that SeaLights scans the right files, resolves the right sources, and catches configuration issues early.

{% hint style="info" %}
`dryRun` does not replace your CI integration.

It creates a local report only and does not send data to SeaLights.
{% endhint %}

## When to use `dryRun`

Use `dryRun` during first-time setup, when the scan includes unexpected files, when source maps do not resolve as expected, or when NYC coverage paths do not line up with the build scan.

It is the fastest way to see what the agent will analyze before you move the flow into CI.

## Before you start

Make sure the `slnodejs` agent is installed. See [Downloading the Node.js Agent](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/downloading-the-node.js-agent.md).

{% hint style="warning" %}
If you scan a minified front-end build, keep the `*.js.map` files next to the built JavaScript files.

* The source maps must point to the correct source files and include column information.
* See [Javascript & Node.js Source Map Files](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/legacy-commands-deprecated/javascript-and-node.js-source-map-files.md).
  {% endhint %}

## Run the command

Since `dryRun` runs locally, it does not require a token or a build session ID.

Start with the smallest command that matches your build.

At minimum, pass `--scanDir` for the build output directory and `--scmType` for the source control type, usually `git` or `none`.

In most cases, add `--verbose` so the console output is easier to read. Use `--instrumentForBrowsers` for front-end browser builds. Add `--hasNycReport` and `--report` only when unit test coverage is part of the integration.

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

```bash
npx slnodejs dryRun --scanDir "./dist" --scmType git --verbose --instrumentForBrowsers
```

{% endtab %}

{% tab title="PowerShell" %}
{% code overflow="wrap" %}

```powershell
npx slnodejs dryRun --scanDir ".\dist" --scmType git --verbose --instrumentForBrowsers
```

{% endcode %}
{% endtab %}
{% endtabs %}

If unit tests are in scope, validate the NYC JSON coverage file in the same run:

{% tabs %}
{% tab title="Bash" %}
{% code overflow="wrap" %}

```shellscript
npx slnodejs dryRun --scanDir "./dist" --scmType git --verbose --instrumentForBrowsers --hasNycReport --report "./report/coverage-final.json"
```

{% endcode %}
{% endtab %}

{% tab title="PowerShell" %}
{% code overflow="wrap" %}

```ps1
npx slnodejs dryRun --scanDir ".\dist" --scmType git --verbose --instrumentForBrowsers --hasNycReport --report ".\report\coverage-final.json"
```

{% endcode %}
{% endtab %}
{% endtabs %}

{% hint style="success" %}
A successful run gives you the number of scanned methods, branches, and files, a summary table with validation results, and an `sl-dry-run-output` folder with the detailed analysis files.
{% endhint %}

After the command completes, use the summary table to find the first issue to fix.

Example output:

{% code lineNumbers="true" fullWidth="true" %}

```
Analysis completed, found the following:
┌───────────────────────────────────────────────────────────┬─────────────────────────┬──────────────────────────────┐
│Name                                                  │Status                 │ Message                   │
├───────────────────────────────────────────────────────────┼─────────────────────────┼──────────────────────────────┤
│Column information                                    │ok                     │                           │
├───────────────────────────────────────────────────────────┼─────────────────────────┼──────────────────────────────┤
│Git paths                                             │ok                     │                           │
├───────────────────────────────────────────────────────────┼─────────────────────────┼──────────────────────────────┤
│Raw third party                                       │ok                     │                           │
├───────────────────────────────────────────────────────────┼─────────────────────────┼──────────────────────────────┤
│Logical third party                                   │ok                     │                           │
└───────────────────────────────────────────────────────────┴─────────────────────────┴──────────────────────────────┘
 1 warnings or error has found. For more information please see sl-dry-run-output/agent-events.json
```

{% endcode %}

All details, including warnings, errors, and logs, are written to `sl-dry-run-output`.

{% hint style="danger" %}
If the agent detects a misconfiguration, check the **Message** column first.
{% endhint %}

## Recommended workflow

{% hint style="info" %}
Start with the smallest real build output you can validate.

That makes the first troubleshooting pass easier to understand.
{% endhint %}

{% stepper %}
{% step %}

### Run `dryRun`

Run the command against the build output folder.

Start with the minimal command first.

Add NYC validation only if unit test coverage is in scope. That keeps the first troubleshooting cycle focused on build scan quality.
{% endstep %}

{% step %}

### Read the summary table

Use the **Status** and **Message** columns to identify the first failing check.

Do not try to fix every warning at once. Start with the first issue that changes scan scope or source mapping.

Those issues often cause the rest of the output to look worse than it really is.
{% endstep %}

{% step %}

### Review generated files and fix the main issues

Open the files under `sl-dry-run-output` to confirm what the agent actually scanned.

Start with `included-files.json` and `excluded-files.json`. These two files tell you whether the right files are in scope and whether the current exclusions are working as expected.

Next, review `sl-mapping.json` to see how source maps resolve back to source files. Use `agent-events.json` when you need the full warning or error details behind the summary table.

By this point, you can usually tell whether the next fix is about scan scope, source maps, or path alignment.

<details>

<summary>Fix scan scope first</summary>

Exclude files that your developers do not maintain first.

This reduces scan time and improves coverage quality. It also makes the rest of the validation easier to interpret.

If `included-files.json` contains bundled framework files, vendor assets, or generated output that should not be part of the project scope, update `.slignore` or `.slignore.generated` and run `dryRun` again.

{% hint style="info" %}
For ignore rule examples, see [Ignoring Files or Folders](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/legacy-commands-deprecated/ignoring-files-or-folders.md).
{% endhint %}

</details>

<details>

<summary>Fix source maps next</summary>

For front-end builds, open `sl-mapping.json` and confirm that each mapped source points to a real file in your repository.

If the paths are wrong, review your build's source map configuration before you continue with other fixes. When source maps are wrong, method names, path alignment, and coverage mapping often become noisy at the same time.

{% hint style="info" %}
See [Javascript & Node.js Source Map Files](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/legacy-commands-deprecated/javascript-and-node.js-source-map-files.md) for source map requirements and examples.
{% endhint %}

</details>

<details>

<summary>Share the output folder with support when you hit a blocker</summary>

If the output still does not make the next fix clear, package the entire `sl-dry-run-output` folder and share it with support.

Attach the ZIP file to a support portal ticket through [Contact Support](https://docs.sealights.io/knowledgebase/contact-support). If you already have an active support email thread, attach the same ZIP there.

Include a short note with the command you ran, the main warning or error, and whether the issue is about scan scope, source maps, or NYC validation.

</details>
{% endstep %}

{% step %}

### Run `dryRun` again

Repeat until the remaining warnings are expected and understood.

When scope and source maps are correct, the remaining issues are usually much easier to resolve.

At that point, you can move on to CI integration with far fewer surprises.
{% endstep %}
{% endstepper %}

### Map each summary item to the next fix

{% hint style="warning" icon="lightbulb-on" %}
If several rows fail, fix scope and source map issues first. Those two issues often make the rest of the output look noisier than it really is.
{% endhint %}

Once you know which row failed, use the table below to choose the most likely next fix.

This mapping helps you move from the command output to the right remediation step without guessing.

<table><thead><tr><th width="220.25">Summary item</th><th>What it means</th><th>What to change</th></tr></thead><tbody><tr><td><code>Column information</code></td><td>Your source maps do not include column information.</td><td>Regenerate source maps with both line and column mapping enabled.</td></tr><tr><td><code>Git Paths</code></td><td>The scanned project structure does not match the Git project structure.</td><td>Check <code>--buildScanProjectRoot</code> and make sure it aligns with your repository root.</td></tr><tr><td><code>Raw Third Parties</code></td><td>The scan includes bundled framework or vendor files.</td><td>Refine your scan scope and add exclusions in <code>.slignore</code>.</td></tr><tr><td><code>Logical Third Parties</code></td><td>Your source maps resolve to generated or third-party source files.</td><td>Fix source map generation and exclude irrelevant mapped files in <code>.slignore.generated</code>.</td></tr><tr><td><code>Nyc Paths</code></td><td>The NYC report paths or signatures do not match the SeaLights build scan.</td><td>Validate <code>--buildScanProjectRoot</code> and <code>--nycProjectRoot</code>.</td></tr><tr><td><code>Position Match</code></td><td>Method and branch positions in the NYC report differ too much from the SeaLights scan.</td><td>Make sure both analyses use the same code baseline and build configuration.</td></tr></tbody></table>

## Common errors

Use these quick answers when you hit a common issue. Expand an item when you need the next step.

<details>

<summary><code>JavaScript heap out of memory</code></summary>

Usually means the process needs more memory or the scan scope is too broad.

First, confirm that the scan only includes files your team maintains. Large bundled files, generated assets, and third-party code can increase memory use quickly.

Then review [JavaScript heap out of memory troubleshooting](/knowledgebase/setup-and-configuration/troubleshooting-faq/node-javascript/nodejs-javascript-heap-out-of-memory.md) for the recommended fixes.

</details>

<details>

<summary><code>Column information</code> warnings</summary>

Usually mean the source maps do not include column mapping

SeaLights needs both line and column information to map methods accurately.

If the warning appears, regenerate the source maps with full column mapping enabled and rerun `dryRun`.

See [JavaScript & Node.js Source Map Files](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/legacy-commands-deprecated/javascript-and-node.js-source-map-files.md) for the expected source map requirements.

</details>

<details>

<summary><code>Failure during instrumentation</code></summary>

Usually means the parser settings do not match the build

Check whether the build uses ES modules, JSX, or both. For ES modules, add `--es6Modules`. For React applications, add `--babylonPlugins jsx`.

If the error continues, review the parser-related options in [Command Reference — Running a local validation (`dryRun`)](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/command-reference.md#dryrun-command-reference).

</details>

<details>

<summary><code>Raw Third Parties</code> or <code>Logical Third Parties</code> warnings</summary>

Usually mean the scan scope or source maps are too broad

Start by checking whether bundled framework files or vendor files appear in `included-files.json`.

If they do, tighten `.slignore` or `.slignore.generated`. If the warning comes from mapped source files, review `sl-mapping.json` and fix the source map configuration.

For ignore rule examples, see [Ignoring Files or Folders](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/legacy-commands-deprecated/ignoring-files-or-folders.md).

</details>

## Command options reference

{% hint style="info" %}
For `dryRun` flags and equivalent command mappings, see [Command Reference — Running a local validation (`dryRun`)](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/command-reference.md#dryrun-command-reference).
{% endhint %}


---

# 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/sealights-agents-and-plugins/node.js-agent/advanced-features/dryrun-command-troubleshooting-and-validation.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.