CLItrail Docs

Common problems

Most problems come from the visit and the install happening in different places. Start with --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.

#Installs show as unmatched

Each one says Safari or External, 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.
  • 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.
  • 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.

#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 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. See 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.

  • 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 has the support matrix, a checklist and a contact form for signed-in users, or email founders@pilotprotocol.network. Paste diagnostics such as --doctor output, never credentials.