> 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/browser-agent/troubleshooting.md).

# Troubleshooting

Start every investigation in the browser developer tools console of an instrumented page, with the agent log level set to `debug`.

## Agent log level <a href="#agent-log-level" id="agent-log-level"></a>

To see the agent's full log, set the log level in a script that runs before the instrumented files:

```html
<script>
  window.$Sealights = window.$Sealights || {};
  window.$Sealights.configuration = { logLevel: 'debug' };
</script>
```

This applies to each build's agent from the start, but some start-up and context propagation messages are still logged at `info` until the level is changed in the running agent. To see every message, also change it after the agent has loaded, in the console:

```js
window.$Sealights.configuration.logLevel = 'debug';
```

Valid levels: `trace`, `debug`, `info`, `warning`, `error`, `critical`, `fatal`, and `off` (no agent logging). An unknown name, for example `warn`, set before the agent loads makes the agent log nothing; set in the running agent, it is ignored. On start-up the agent prints its configuration, with the token obfuscated.

## Agent not loading <a href="#agent-not-loading" id="agent-not-loading"></a>

**Symptom:** `window.$SealightsAgent` is `undefined`, or the console shows no `has been loaded` line. (`window.$SealightsAgent` is also defined when the agent rejected every build's configuration; then see [Agent loaded but no footprints](#agent-loaded-but-no-footprints).)

| Check                                                                         | Fix                                                                                                                                                                                                                                                                                                                                 |
| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The page serves the original files, not the instrumented ones.                | Deploy the instrumented output (`sl_dist`). `window.$Sealights.components` is set only by instrumented files.                                                                                                                                                                                                                       |
| The network tab shows a failed request for the agent script.                  | Allow the browser to reach SeaLights (or the Collector, when the build has a Collector URL). Check the content security policy; see [Configuration → Content security policy](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent/configuration.md#content-security-policy). |
| The network tab shows a 404 for `sl-preamble-config.js`.                      | The build was instrumented with `--splitPreambleIntoFile` and the preamble file is not served at that URL. Deploy it. On deep routes of a single-page application, instrument with a full-URL `--preambleFileUrl`, or set `<base href>`.                                                                                            |
| `--allowedDomains` was set at instrumentation and the host name is not in it. | Add the host name, or instrument without `--allowedDomains`.                                                                                                                                                                                                                                                                        |
| `window.$Sealights.skipSlAgent` is set.                                       | Remove it.                                                                                                                                                                                                                                                                                                                          |
| The console shows `Sealights browser listener failed to start`.               | Collect the console output and contact SeaLights support.                                                                                                                                                                                                                                                                           |

## Agent loaded but no footprints <a href="#agent-loaded-but-no-footprints" id="agent-loaded-but-no-footprints"></a>

| Check                                                                           | Fix                                                                                                                                                                                                                                                                                                                                                    |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| The console shows `Detected an invalid configuration` and names a field.        | The named field is empty in the build's configuration. Re-instrument with the missing value (for example the token, or the application, branch or build name of the build session).                                                                                                                                                                    |
| `blockBrowserHttpTraffic` is `true` in the printed configuration.               | The agent sends nothing by design. Re-instrument without `SL_blockBrowserHttpTraffic`.                                                                                                                                                                                                                                                                 |
| No test stage is open for the agent's lab ID.                                   | Open the test stage with the same lab ID the agent uses. The agent logs it as `LabId:<value>`; see [Configuration → Lab ID](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent/configuration.md#lab-id).                                                                                       |
| The page closes before footprints are sent.                                     | Footprints collected since the last periodic send are lost when the page closes. Call `window.$SealightsAgent.sendAllFootprints()` before closing; see [Footprints when the page closes](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent/configuration.md#footprints-when-the-page-closes). |
| The token was excluded (`--excludeTokenFromBrowserConfig`) without a Collector. | Instrument with `--collectorUrl` as well, or include the token.                                                                                                                                                                                                                                                                                        |

## sl-mapping not found <a href="#sl-mapping-not-found" id="sl-mapping-not-found"></a>

**Symptom:** the console shows `Error while trying to load slMapping from server`.

The agent downloads the build's sl-mapping from SeaLights to resolve footprints, unless the build was instrumented with `--footprintsMapping server` or `--embedCorrectUniqueId`. Check that the build session in the printed configuration finished its scan successfully, and that the browser can reach the server in the printed configuration. Inspect the mapping the agent holds with `window.$SealightsAgent.getSlMapping()`; an empty object means no mapping was loaded.

## Context propagation headers missing <a href="#context-propagation-headers-missing" id="context-propagation-headers-missing"></a>

| Check                                                                                   | Fix                                                                                                                                                                                                              |
| --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `window.$Sealights.eventsBridge.otel` is not `true`.                                    | Instrument the build with `--enableOpenTelemetry`; see [Context Propagation](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent/context-propagation.md). |
| The console shows `Not adding header ... because of origin difference`.                 | The request goes to an origin that is not in `--allowCORS`. Add that origin, and the page's own origin, to `--allowCORS` of `slnodejs scan --instrumentForBrowsers`, or use `*`.                                 |
| Requests to another origin fail in the browser with a CORS error.                       | The back end does not allow the propagation headers in its CORS preflight. Add `baggage` to its `Access-Control-Allow-Headers`.                                                                                  |
| Coverage is attributed to the previous test after `delete:baggage` or `delete:context`. | The build has no `--enableOpenTelemetry`, or the context was set with `set:context` and restored from session storage.                                                                                           |
| `window.$Sealights.eventsBridge.getBaggage()` returns nothing.                          | No test is set. Dispatch `set:baggage` with `x-sl-test-session-id` and `x-sl-test-name`.                                                                                                                         |
| The console shows `Received setBaggage event with with missing testName/executionId`.   | Send both required values.                                                                                                                                                                                       |
| The build was instrumented with `slnodejs instrument --allowCORS`.                      | `instrument` drops the list. Instrument with `slnodejs scan --instrumentForBrowsers --allowCORS`.                                                                                                                |

## Pages load slowly or tests time out after instrumentation <a href="#slow-pages" id="slow-pages"></a>

* Instrument with `SL_reduceInstrumentedFileSize=true` (on `scan --instrumentForBrowsers`; `instrument` does it by default).
* Use `--footprintsMapping server` so the browser does not download the sl-mapping.
* Exclude vendor bundles with `.slignore.instrument` or `--skipInstrumentingFilesWithoutSourceMap`.

See also [Cypress Plugin - Tests Timing Out](https://docs.sealights.io/knowledgebase/setup-and-configuration/troubleshooting-faq/node-javascript/cypress-plugin-tests-timing-out.md) and [JS: Reducing SeaLights Logging for Instrumented Code](https://docs.sealights.io/knowledgebase/setup-and-configuration/troubleshooting-faq/node-javascript/js-reducing-sealights-logging-for-instrumented-code.md).

## Collecting information for support <a href="#collecting-information-for-support" id="collecting-information-for-support"></a>

Send SeaLights support:

1. The console output of a page load with the log level set to `debug`.
2. The value of `JSON.stringify(window.$Sealights.components)`, with the token removed.
3. The network requests to SeaLights or to the Collector, with their status codes.
4. The `slnodejs` command that instrumented the build, and the `slnodejs` version.


---

# 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/browser-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.
