# Troubleshooting

What to check when a form does not load, an answer is refused or a token is ignored.

Start with the browser console. When something on your side needs fixing, the widget says so once, in a line that starts with `OneStar:`, and the element fires `onestar:error` with a code (see [Events and errors](https://onestar.sh/docs/feedback/events.md)).

## The form does not appear

An inline form loads when it comes within about 200 pixels of the screen, and an overlay loads when it opens. If the element is far down the page, scroll to it before you look for errors.

Then match the console line:

```text Console
OneStar: "f_hemsz66" is not a form id. Copy it from the form's Install tab.
```

The `form` attribute is not a whole form id. Copy it from the form's **Install** tab: `f_` and 16 characters. The element fires `invalid_form`.

```text Console
OneStar: form f_hemsz66yupbd76d2 was not found or is not live. Check the id on the form's Install tab.
```

No form has that id, usually a typo. The element shows the closed message and fires `form_closed`.

```text Console
OneStar: form f_hemsz66yupbd76d2 does not allow https://www.example.com. Add https://www.example.com under Install, Allowed sites in OneStar.
```

The page's site is not in the form's allowed sites. The card stays hidden and the element fires `origin_refused`. Sites must match exactly: `https://example.com` and `https://www.example.com` are two sites, and each `localhost` port is its own. The **Install** tab lists sites that tried to show the form but are not allowed, with a button to add each one.

```text Console
OneStar: form f_hemsz66yupbd76d2 could not load: the OneStar API did not answer. Check the connection, that connect-src allows https://api.onestar.sh, and that https://www.example.com is in the form's allowed sites.
```

The request for the form never got an answer the page could read. Check, in order: your Content Security Policy has `connect-src https://api.onestar.sh`; the network tab shows the request to `api.onestar.sh` was not blocked by an extension, a proxy or a firewall; and the site is allowed. The element fires `network`.

```text Console
OneStar: the feedback renderer could not load from https://embed.onestar.sh/v1/renderer.<hash>.js. Likely causes: a Content Security Policy whose script-src does not allow https://embed.onestar.sh, or a blocked request (an ad blocker, a proxy or firewall, no network).
```

The widget's script could not load. Allow `https://embed.onestar.sh` in `script-src`, and try with ad blocking off to see whether a blocker is the cause. The element fires `load_failed` and tries again the next time it opens or scrolls into view. The [security page](https://onestar.sh/docs/feedback/security.md) lists every policy line the widget needs.

### The form says it is not taking answers

The form exists but is closed to answers. Visitors see your closed message, or "This form is not taking answers right now." In OneStar, a form that was never published, or that you paused or closed, shows that state. A live form that still cannot take answers shows **Not taking answers** with the reason: its close date passed, it reached its answer limit, your answers for the month reached the most your plan stores, your plan does not include forms, or its settings need another look. Fix that, and the next page load shows the form.

## An answer is refused

The form tells the person what to do in plain words. The code on `onestar:error`, or on the rejection from `onestar.submit`, tells you why:

| Code | What happened | What to do |
|---|---|---|
| `origin_refused` | The page's site is not allowed. | Add it under **Allowed sites**. |
| `form_closed` | The form closed while the page was open. `onestar.submit` rejects with `closed`. | See the reason in OneStar. |
| `identity_required` | A form for signed in users got no token, or a token it could not accept. | See [Signed in users](https://onestar.sh/docs/feedback/identify-users.md#when-a-token-is-not-accepted). |
| `stale_form` | The page was open long enough for the form to expire. | The person gets a Reload button. Nothing to fix. |
| `version_changed` | You published a new version while the person was answering. | The person gets a Reload button. |
| `too_fast` | The answer came sooner after loading than a person could send it. | The widget waits and sends once more. From your own UI, wait a moment before sending. |
| `not_found` | A later step of an answer came too long after its first. | The person reloads and answers again. |
| `rate_limited` | Too many answers in a short time. | The person gets Retry. |
| `server`, `network` | A failure on the way or on OneStar's side. | The person gets Retry. |

A wrong answer the person can fix (`invalid_answer`) and a second answer to a form set to one answer per person (`already_answered`) are not errors: the form shows the message and fires nothing. From your own UI, `onestar.submit` rejects with them, and `fields` holds a message per question id.

## A signed token is ignored

OneStar never says why it refused a token. On a form open to anyone, the answer is simply stored as anonymous; on a form only for signed in users, the person sees your sign in message. The most common causes are a secret used without its `oss_` prefix, `sub` sent as a number, and `exp` in milliseconds or more than 24 hours ahead. Work through the [checklist](https://onestar.sh/docs/feedback/identify-users.md#when-a-token-is-not-accepted).

## Answers do not show in Results

- **They are test answers.** Answers from `localhost` or `127.0.0.1`, and every answer while the form is in test mode, never reach Results. The form showed a Test ribbon. Find them in the **Test answers** card on **Install**. See [Testing](https://onestar.sh/docs/feedback/testing.md).
- **A filter is on.** Clear the filters and the time window on **Results**.
- **The questions changed.** Results counts every version that asks the same questions as the live one. If you added, removed or retyped a question, earlier answers are under their own version: pick it in the version menu.
- **The person deleted it.** Someone you replied to can delete their answer from their conversation page, and it leaves Results.
- **The month is full.** When your answers reach the most your plan stores, new answers are refused until the month resets, and OneStar notifies you.
- **It came from the form's own page while the form was private.** The form's own page, and the web view page built on it, take answers only while the form is shared by link or publicly on its **Share** tab.

## A native app's web view does not close

The form page tells your app when the person finishes, with the message `{ "type": "onestar:submitted", "form": "f_..." }`. It goes to each of these that your app installed:

- iOS: a script message handler named `onestar` on the web view (`window.webkit.messageHandlers.onestar`).
- React Native: the web view's `onMessage`, as a JSON string.
- Android: a JavaScript interface named `OneStarAndroid` with an `onMessage(String)` method.

Check that the name matches exactly. The message is sent when the answer is finished, not on the first tap. A person who already answered this version sees the thank you message at once and no message is sent, so always give the view its own close button. See [Native apps](https://onestar.sh/docs/feedback/native-apps.md).

## Webhooks fail

In **Settings**, **Feedback API**, a webhook that keeps failing is marked stopped, with the last error under it. Common causes:

- Your endpoint answers with a status other than 2xx, or a redirect (redirects are not followed).
- Your endpoint takes too long. Answer first, then do the work.
- The address is not reachable from the internet, or resolves to a private address.
- Your signature check fails, so your code answers with an error: check against the raw body, use the whole `whsec_` secret as text, and make sure your clock is right.

Fix the endpoint, then choose **Turn on**. See [Webhooks](https://onestar.sh/docs/feedback/webhooks.md).