FAQ & troubleshooting
Central troubleshooting for connections, data, GTM, plans and error codes: symptom → cause → action.
Connections & authorization#
| Symptom | Cause | Action |
|---|
| Reports still empty after authorizing | Unbound resource, or upstream latency | Pick the GA4 property / GSC property in Settings; wait 24-48 hours |
| "Insufficient permission" | Bound resource is not under that Google account, or the GSC property type is wrong | Re-pick the resource; do not confuse domain vs URL-prefix properties |
| URL Inspection reports missing permission | Old read-only grant | Use "Re-authorize" on the Google API page to gain write scope |
| Invalid token (invalid_grant) | Revoked or expired on the user side | Re-authorize |
| Data mixed across sites | Each site binds its own resources | Switch with the header site picker and verify bindings per site |
Data & definitions#
| Symptom | Cause | Action |
|---|
| No data right after connecting | Upstream latency (GA4 24-48h, GSC 1-2 days, PSI ~6h) | Wait; the system backfills |
| Numbers disagree with another tool | Different definitions / windows / sampling / time zones | See "Data latency & metric definitions" |
| PSI score occasionally missing | Upstream quota or timeout | The next refresh restores it |
| Little AdSense page-level data | PAGE_URL has a minimum-impression threshold | Rely on domain-level totals |
| Edge requests far exceed sessions | Cloudflare counts all HTTP requests incl. static and bots | A normal definition difference |
GTM & events#
| Symptom | Cause | Action |
|---|
| Import JSON says "invalid file format" | Not export format 2 / wrong enum casing | Download the latest import file again from the console |
| Imported but no live data | The version was not published in GTM | Versions → Publish |
| Duplicate entities | The same names were imported twice | Import once, or choose "Overwrite" |
| Everything looks right but nothing fires | Site loads container A, this binds container B | Match the GTM-XXXX in the page source with the bound container |
| Tag parameters are empty | Built-in variables not enabled | Variables → Configure → enable the needed built-ins |
| Forms / outbound clicks do not fire | fetch-only submission; or outbound trigger without "Wait for tags" | Use a custom event; enable waiting (2000ms) |
Plans & quotas#
| Symptom | Cause | Action |
|---|
| A feature says "upgrade to unlock" | Locked on the Free plan | See "Plans & feature gating" |
| URL Inspection quota exhausted | Daily quota (Free 0 / Pro 50 / Business 200) | Wait for the UTC midnight reset, or upgrade |
| MCP data tools error out | Free allows only metricskit_ask | Upgrade to use all tools |
| Incomplete AdSense page-level data | Impression threshold | Use domain-level data |
Error codes#
| Code | Meaning | Action |
|---|
| CONNECTION_REQUIRED | Service not connected (403) | Connect the data source |
| GOOGLE_AUTH_REQUIRED | Google token invalid (503) | Re-authorize |
| TOKEN_REFRESH_FAILED | Token refresh failed (503) | Disconnect and reconnect |
| GA4_NOT_BOUND / NO_GA4_PROPERTY | No GA4 property selected | Pick one in Settings |
| NO_GSC_PROPERTY | No GSC property bound | Bind it in Settings |
| GSC_PERMISSION_DENIED | Wrong property type or no access (403) | Re-pick the property |
| NO_ADSENSE_ACCOUNT / ADSENSE_MULTIPLE_ACCOUNTS | No account / multiple accounts need a manual pick | Follow the prompt |
| PSI_UNAVAILABLE_OR_QUOTA | PSI quota or timeout | Recovers on the next run |
| PLAN_REQUIRED | Plan too low (403) | Upgrade |
| AI_NOT_CONFIGURED | No model configured (503) | Page falls back to demo data |
| BILLING_NOT_CONFIGURED | Billing not configured (503) | Contact the admin |
| CF_TOKEN_INVALID | Cloudflare token invalid (400) | Paste a valid token |
| UPSTREAM | Upstream error (502) | Retry later; check the upstream status if it persists |
- Site connections & authorization (/connections)
- Data latency & metric definitions (/data-latency)
- GTM console guide (/gtm-console)
- Plans & feature gating (/plans)