# Common problems

Most problems come from the visit and the install happening in different places. Start with [`--doctor`](https://clitrail.com/docs/doctor) on the installing computer.

### Installs show as counted

The organisation is on Free, or the install path is paused after a downgrade. Nothing is matched on Free, and installs reported there are never matched later. Upgrade, or keep the path in **Install paths**. See [No attribution on Free](https://clitrail.com/docs/plans#no-attribution-on-free).

### Installs show as unmatched

Each one says [Safari or External](https://clitrail.com/docs/unattributed), which points at the fix.

- **Different browser or computer.** The visit must happen in a supported browser for the same OS user on the same computer. Safari, Windows browsers with WSL, remote agents and containers need the [handoff command](https://clitrail.com/docs/handoff).
- **The visit was not recorded.** In the browser console on your install page, run `await InstallAttribution.ready`. Anything other than `ok: true` gives the [reason](https://clitrail.com/docs/sdk#the-result).
- **The origin is not registered.** `https://www.acme.dev` and `https://acme.dev` differ. Add the missing one under additional domains.
- **The hook did not run, or ran elsewhere.** It skips CI and opt-outs, needs curl or wget, and must run as the visitor's user, not under `sudo`.
- **The receipt is gone.** Private windows, cleared site data and receipts older than 30 days cannot match.
- **The hook ran before the install finished.** A report is resolved when it arrives; reporting again later does not attach a receipt.

### Installs show as ambiguous

The website uses the `unique` policy and the install found several visits. Choose latest or first visit in **Settings** to credit one of them. See [Attribution policies](https://clitrail.com/docs/attribution-policies).

### `opfs_unavailable`

The page is not a secure context (plain http on a host other than `localhost`), or the browser does not provide OPFS. Serve the page over https.

### Nothing reaches a destination

- Is it live? Test-mode deliveries show `dry_run`.
- Is the organisation on Standard or Enterprise, and is the destination within the plan’s limit? Destinations are paused on Free and over the limit.
- Is the event type ticked, and was the install `matched`? Reconstructed installs need **Include reconstructed installs** on the destination. Paths that report `first_run` need it ticked on ad destinations.
- Did the journey carry that platform's ID? Without a GA4 client ID, a Google click ID, `fbc`/`fbp`, `ttclid`/`ttp` or a `twclid`, nothing is queued for it. Visits made with Global Privacy Control, shown with a **GPC** badge, never reach ad platforms.
- Google Ads sends nothing when ad user data is set to denied, or when the click is more than 90 days old. X Ads sends nothing for clicks older than the destination’s click window, and first runs only with a first-run event ID.
- [Logs](https://clitrail.com/docs/logs) show every attempt with the platform’s exact answer.
- Check the destination's health and each delivery's status on **Install events**. `auth_error` means the platform refused the credential: replace it, and the queued events are sent at once.
- `install_started` reaches webhooks only.

### Go live is refused

The message names what is missing: a paid plan, credentials, the terms confirmation or [domain verification](https://clitrail.com/docs/domain-verification). See [Go live](https://clitrail.com/docs/destinations#go-live).

### A limit is reached

`402` `plan_limit` names the limit and its maximum on your plan. **Usage** in the dashboard shows where you stand. See [Plans and limits](https://clitrail.com/docs/plans).

### An invitation link does not work

- Sign in as the invited address: with its Google account, or with an email link sent to it (an email link always verifies the address).
- Links work once and for 7 days. Ask an admin for a new one.
- An organisation at its member limit takes nobody new, pending invitations included.

### `secrets_require_https`

The service refuses credentials over plain http. Use the https address of your CLItrail dashboard.

### Webhook signatures do not verify

- Verify the raw body. Frameworks that parse JSON first change the bytes.
- Use the whole secret, including `whsec_`, as shown when created or last rotated. After a rotation, accept any of the space-separated signatures.
- Check your server's clock: timestamps more than five minutes away are rejected.

### Still stuck

The [support page](https://clitrail.com/support) has the support matrix, a checklist and a contact form for signed-in users, or email [founders@pilotprotocol.network](mailto:founders@pilotprotocol.network). Paste diagnostics such as `--doctor` output, never credentials.