---
title: Troubleshooting
description: Diagnose initialization, missing surveys, events, targeting and response delivery.
url: https://docs.userreason.com/get-started/troubleshooting/
updated: 2026-10-18
---

# Troubleshooting

Start by checking configuration loading, then survey eligibility, then response delivery. A successful initialization alone does not guarantee a survey should appear.

## Enable diagnostics

Add `debug: true` to your existing `init()` options and reload. Register an error listener before initialization:

```ts
import UserReason from '@userreason/js';

UserReason.on((notification) => {
  if (notification.type === 'error') console.error(notification.error);
});
UserReason.init({ siteId: 'YOUR_SITE_ID', debug: true });

try {
  await UserReason.ready();
} catch (error) {
  console.error('UserReason initialization failed', error);
}
```

Replace the site ID. Repeating `init()` on a running instance will not enable debugging; edit the original initialization and reload. Debug logs omit visitor values and tokens.

## Configuration or session will not load

Check that browser code actually runs, the site ID belongs to the intended active site, and the API origin is correct. In the Network panel, inspect failed configuration and session requests. Check the browser console for CSP blocks or a denied origin. A site configured with allowed origins needs the exact scheme, host and port.

Do not put management tokens in the SDK to fix a browser request. The public site ID is sufficient for ordinary anonymous initialization.

## ready() succeeds but no survey appears

| Check | What to verify |
| - | - |
| Publication | The survey is published and active on this site. Draft edits need another publish. |
| Configuration | Refresh or reload after publishing. Automatic refresh defaults to 60 seconds. |
| Trigger | The current opportunity matches. `show()` needs a page-load trigger; event-only surveys need `event()`. |
| Audience | Required traits, verified facts and history are present for this visitor. |
| Sampling | Use 100% on the development survey while debugging. Stable sampling does not reroll every time. |
| Frequency | The visitor is not held by the survey's or the site's frequency settings, and has not permanently declined. A user's Eligibility in the dashboard names the limit and when it ends. |
| Workspace allowance | The workspace has remaining monthly responses. Overview and Workspace settings show usage and the next UTC reset. |
| Display availability | The document body exists and another UserReason widget is not already open. |
| SDK capabilities | The installed SDK supports the question types in this survey. |

Use a development site and fresh private browsing session for an isolated test. For an identified account, server history still follows that account. `reset()` and `force: true` do not erase server frequency records.

## An event returns false

This does not by itself mean collection failed. The event can be recorded while no matching survey qualifies. Check the site's Events tab, event capture policy, name and property schema, then the survey's trigger and eligibility. Registered-only sites need the event registered first.

An empty event name rejects. Other managed event errors report an `error` notification and resolve to false. [Application events](https://docs.userreason.com/sdk/events/index.md) describes the exact contract.

## Verified targeting does not qualify

Check that your backend derives the account ID and trusted values from authenticated server data. Obtain fresh assertions rather than reusing expired ones. Identity tokens and event proofs last 60 seconds when issued; they serve different purposes.

A browser trait does not satisfy `verified_trait`. A plain event property does not satisfy `verified_event_property`. Backend and SDK event histories are distinct, and missing history is not a known zero count.

## Response submission fails

Inspect the failed submission request and `error` notification. Temporary delivery failures keep answers available for retry. Closing, resetting or destroying the SDK aborts pending work.

HTTP 409 with `workspace_response_limit` means the workspace's monthly allowance is exhausted. The free plan includes 10,000 responses across all sites in a workspace, resetting at 00:00 UTC on the first day of each month. A response counts once when its first answer is saved, including a partial response; later answers and completion do not count again. Already counted responses can finish after exhaustion. SDK 0.4.1 shows the quota explanation and prevents further save attempts for a rejected response. Check usage in the dashboard or see [pricing](https://userreason.com/pricing/) for a higher allowance.

Read managed responses in the dashboard or with `prompt responses`. The SDK's `submitted` notification indicates successful response delivery, whereas `shown` only indicates visible rendering.

## CLI access is denied

Run `whoami` to check the signed-in account and environment. Sign-in does not grant site management access: request the required scopes for the correct workspace and site, then have a person approve the printed URL. Expired or rejected grant requests need a new request.

A revision conflict means the survey changed since you read it. Read it again, review the current definition, and use that revision for the next intended change. See [CLI commands and access](https://docs.userreason.com/cli/index.md).