> ## Documentation Index > Fetch the complete documentation index at: https://citdhq.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting > Symptom-by-symptom fixes for common issues in Citd. Something not working the way you expect? Find your symptom below, check the likely cause, and follow the fix. If you still need help after trying these steps, see [Getting more help](#getting-more-help) at the bottom of this page. **Likely cause:** The first tracking run has not finished yet, or — on the Free plan — your weekly run has not run since you completed onboarding. **Fix:** 1. Check the **freshness bar** at the top of the [Overview](/features/overview) page. It tells you when data was last updated and when the next run is expected. 2. If you just finished onboarding, give the first run a few minutes to complete. The initial analysis includes topic generation, prompt generation, and a full tracking pass — it takes longer than a regular run. 3. On the **Free plan**, tracking runs weekly. If you signed up mid-week, you may be waiting for the next scheduled window. Upgrading to Starter or Growth unlocks daily tracking and the ability to trigger a manual run from [Project Settings](/features/project-settings). 4. If the freshness bar shows a completed run but the dashboard is still empty, try a hard refresh (Cmd+Shift+R / Ctrl+Shift+R). If it persists, contact support. Free plan tracking runs once per week. If you need fresher data sooner, consider upgrading — see [Plans](/plans). **Likely cause:** Your brand has relevance or authority gaps that prevent it from being recommended for the tracked queries. This is a signal to investigate, not a bug. **Fix:** 1. Open the [Analysis](/features/analysis) page (available on paid plans). 2. Check the **Relevance** section — look for repeated attribute gaps. Your product titles, descriptions, or metadata may not match the language buyers use in your tracked prompts. 3. Check the **Authority** section — if competitors appear in editorial "best of" lists and you do not, that gap suppresses your recommendations. 4. Check **Readiness** — missing metafields, generic descriptions, or absent structured data (JSON-LD) reduce how well AI models understand your products. 5. Use [Actions](/features/actions) to see ranked recommendations, and [Products](/features/products) to inspect individual product issues. A hiking gear store tracking "best trail running shoes for women" may appear for the broad query but not the specific one — that is a relevance gap. Updating product descriptions to match specific use cases (terrain, fit, feature specs) usually moves the needle within 1–2 weeks. **Likely cause:** Your reverse proxy is not configured correctly — most often a missing header, a redirect instead of a 200 response, or a canonical URL that points to the citdhq.com origin instead of your domain. **Fix:** The verifier checks five things. Work through each one: 1. **Status code** — your blog index page (e.g. `yourdomain.com/blog`) must return HTTP `200 OK`. If it returns a `3xx` redirect, the check fails. Make sure your proxy is not redirecting the root path. 2. **SSR marker** — the HTML body must contain `citdhq-feed-origin` or `agentrank-feed-origin`. This means the proxy must forward the `Accept` header. Without it, Citd returns JSON instead of HTML and the marker is absent. 3. **Canonical alignment** — the canonical URL in your blog's `` must match your configured base URL, not a citdhq.com URL. 4. **Health endpoint** — `yourdomain.com/blog/_citdhq/health` must return HTTP `200 OK` with the `agentrank-feed-origin` marker in its JSON body. 5. **Sitemap domain** — `yourdomain.com/blog/sitemap.xml` must list URLs on your own domain, not raw `citdhq.com` URLs. See the [AI Feed](/features/ai-feed) page for the full proxy setup requirements. If your proxy is running on a platform (Vercel, Netlify, Nginx, Cloudflare), make sure `X-Forwarded-Host` and `X-Forwarded-Proto` are also being forwarded. **Likely cause:** An expired authorization link, an incorrect shop domain format, or insufficient token scopes. **Fix:** 1. **Check your shop domain format** — Citd needs the `.myshopify.com` domain (e.g. `your-store.myshopify.com`), not your custom storefront domain. 2. **Check token scopes** — if you created a custom app token, make sure it includes `read_products` and `write_products` in the Admin API configuration. Tokens with missing scopes will connect but fail silently on catalog sync. 3. **Check token validity** — if you generated the token more than a few minutes ago or revoked it in Shopify, generate a new one and try again. Admin API access tokens starting with `shpat_` do not expire on their own, but revoked tokens are invalid immediately. 4. **Try reconnecting** — open [Project Settings](/features/project-settings) under **Store access**, disconnect if partially connected, and reconnect with fresh credentials. For the full connection guide, see [Connect Shopify & Search Console](/setup/integrations). If you are connecting via the Shopify App Store, see [Using Citd inside Shopify](/setup/shopify-app). **Likely cause:** A freshness issue (the run used different data than expected), a filter change, a competitor making a strong move, or a model/topic scope mismatch. **Fix:** 1. **Check freshness first** — the freshness bar on [Overview](/features/overview) shows when data was last updated. A stale run can make a dip look worse than it is. 2. **Check your filters** — make sure the Model, Topic, and Market filters match what you were looking at before. A narrower filter can surface a slice that naturally has lower visibility. 3. **Look at competitors** — if a competitor gained ground, your share of voice may have dropped even if your absolute Visibility held steady. Check the Competitors view for recent movement. 4. **Check the Analysis page** — a sudden drop in a specific metric often has a root cause in Authority, Relevance, or Readiness. Open [Analysis](/features/analysis) and look for the dimension that changed most. 5. **Wait one more cycle** — if the drop appeared in a single run, check again after the next run. Tracking runs can occasionally reflect transient model behavior. See [Overview](/features/overview) for help interpreting the metric cards, and [Analysis](/features/analysis) for root-cause diagnostics. **Likely cause:** These features are only available on paid plans (Starter, Growth, or Managed). On the Free plan, you will see preview sections or locked states for these pages. **Fix:** Upgrade to Starter or higher from [Project Settings](/features/project-settings). See [Plans](/plans) for a full comparison of what each tier includes. Free gives you full access to Overview, Prompts, Sources, and Competitors. Analysis, Actions, and AI Feed are paid-plan features. *** ## Getting more help If your issue is not covered here, or the steps above did not resolve it: * **Check the [FAQ](/faq)** — it covers common questions about integrations, plans, and how Citd works. * **Email us** at [support@citdhq.com](mailto:support@citdhq.com) — include your project URL, the symptom you are seeing, and any error messages. Screenshots help a lot.