> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usertour.io/llms.txt
> Use this file to discover all available pages before exploring further.

# setDebug()

> Turn on Usertour.js console logging to see what the SDK is doing

Usertour.js is silent in the browser console by default — it runs inside your production pages. When content does not show or a step does not attach, turn logging on to see what the SDK is doing: how the connection is going, which element it looked for, which attribute the server refused.

## Turning logging on

Any of the three works. The first two need no code change.

**In the console.** Open the browser's developer tools and run:

```javascript theme={null}
usertour.setDebug(true);
```

Logging starts immediately and stays on for future page loads until you run `usertour.setDebug(false)`.

**In the URL.** Add `?usertour_debug=1` to the page's address and reload. Logging is on for that page load only — useful when you want a screenshot from someone else's browser without changing anything on their machine. The parameter must be in the query part, before any `#`, and the page you land on must keep it: a login redirect that rewrites the URL drops it.

**In code.** Call `usertour.setDebug(true)` after `usertour.init()`. With the npm package (`usertour.js` 0.0.26 or newer) or an installation snippet copied from **Settings → Installation** after this release, the call is queued until the script has loaded, so it can sit anywhere. An older snippet does not know the method: calling it before the script has loaded throws and stops the rest of your script, so there, use the console or the URL instead.

## Parameters

<ParamField path="enabled" type="boolean" required>
  `true` opens the console log, `false` closes it and forgets the persisted setting.
</ParamField>

## Reading the output

Every line starts with `[usertour-widget:<component>]`, followed by the message and the milliseconds since the previous line. The component tells you where to look:

| Component | What it logs |
| :- | :- |
| `socket` | The realtime connection: every state change (`Connection connecting → connected`), each failed connection attempt, reconnects, credential changes, messages that failed to send |
| `core` | Attributes the server refused, and a deprecated attribute operation the SDK rewrote |
| `conditions`, `wait-timer`, `trigger` | Auto-start and trigger conditions being evaluated, wait timers starting and firing |
| `flow`, `checklist`, `banner`, `launcher`, `resource-center` | Each content type attaching to the page, and a target element it gave up on |
| `ui` | The Usertour container and stylesheet loading |

Levels follow the browser's own: informational lines use `console.log`, degraded-but-continuing situations `console.warn`, failed operations `console.error`.

Two messages are shown **even when logging is off**, because they mean Usertour will not work on the page and nothing else would tell you:

* **UI initialization failed** — the stylesheet or the container could not be set up after several attempts, so no content can render. Check that `js.usertour.io` (or your self-hosted assets host) is reachable from the page.
* **Connection rejected by the server** — the environment token or the [identity token](/developers/identity-verification) was refused, and the SDK has stopped reconnecting. Check the token passed to `init()`; with identity verification on, refresh the identity token and call `identify()` again.

## By symptom

**Nothing shows at all.** Look for `[usertour-widget:socket]` lines. `Connection connecting → connected` followed by `Connected` means the network is fine. Only `Connection idle → connecting` and then `Connection attempt failed (…)` lines, never a `Connected`, means the server cannot be reached at all — the message in parentheses (`websocket error`, `xhr poll error`) is the browser's reason, usually a proxy, a firewall or a blocking extension. A `Connection … → reconnecting` that never reaches `Connected` points at the network dropping later; `Connection rejected by the server` points at credentials. Once connected, content that still does not show did not match its start conditions for this user or page — check them in the builder, or ask the server with the API's diagnose tools.

**A step does not attach.** Look under `flow` for `Step target element was not found on the page` — the selector matched nothing for the configured number of seconds (`setTargetMissingSeconds`, else the theme's setting, else 6 seconds), and the line says what happened next: the step was shown as a bubble or the flow was closed. `Step target element stayed hidden past the timeout` is the same for an element that exists but never became visible. `Step has no target element configured` means the step itself is missing a target in the builder. Launchers and banners log `has no target element configured` / `has no container element configured` the same way.

**Attributes are not updating.** Look for `Failed to send UpsertUser` under `socket` — the write never reached the server — or, under `core`, `Attribute "<name>" was not written: <reason>`: the server refused that one value (it does not fit the attribute's type, or the attribute is assigned by Usertour) and wrote the rest. The same reason comes back in the promise: `const { rejected } = await usertour.updateUser(…)`.

In the browser's network panel, a healthy page has one `wss://` connection to your Usertour server carrying `client-message` frames; a connection that keeps reopening is a rejection or a proxy closing idle sockets.

## Notes

* `setDebug` needs a server of this version or newer: on an older self-hosted server the SDK it serves does not have the method, in the console either.
* Logging goes to the console only. Nothing is sent to Usertour.
* The setting is per browser, stored under `localStorage.debug` next to other tools that use the same convention; `usertour.setDebug(false)` removes only Usertour's entry.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.