AI Search troubleshooting: locating and fixing high-frequency failures
The most common production failures for AI Search and their root-cause fixes.
On this page
Quick answer
What are the hard requirements for FAQPage structured data?
Every Question needs an acceptedAnswer, and the Q&A must be truthful and verifiable. Fabricated answers get downranked by ChatGPT Search and Perplexity.
Machine-readable page data: /data/ai-search-troubleshooting.json
In-depth analysis
AI search engines prefer structured Q&A (FAQPage) and a clear content hierarchy; plain prose rarely gets cited as the answer. Troubleshoot by three layers — build, deploy, runtime — diagnose by symptom, never blind-trial.
// FAQPage node: feeds Perplexity / ChatGPT Search with answer pairs
{ "@type":"FAQPage", "mainEntity": [
{ "@type":"Question", "name":"...",
"acceptedAnswer": { "@type":"Answer", "text":"..." } }
] }AI Search Troubleshooting · Key takeaways
- Build, deploy, or runtime layer identified
- Relevant logs and status codes captured
- Fix verified and reproducible
- Fix notes recorded for reuse
FAQ & pitfalls
What happens when the homepage does not expose an ItemList?
AI engines struggle to understand the matrix structure and citations scatter. Add an ItemList on the homepage so engines can build a page relationship graph.
How does AI search result cache update?
Update FAQPage and ItemList and rebuild static pages — engines pick up the new answers on their next crawl. No manual refresh needed.
Explore the hub
See all 5 guides in PerformanceSame category as this article, sorted across the codebase.
Astro troubleshooting: locating and fixing high-frequency failures
The most common production failures for Astro and their root-cause fixes.
Cloudflare Pages troubleshooting: locating and fixing high-frequency failures
The most common production failures for Cloudflare Pages and their root-cause fixes.
GEO troubleshooting: locating and fixing high-frequency failures
The most common production failures for GEO and their root-cause fixes.
SEO troubleshooting: locating and fixing high-frequency failures
The most common production failures for SEO and their root-cause fixes.
Share & save
What readers are asking
Questions that keep coming back in reader feedback, already answered.
- 01
What are the hard requirements for FAQPage structured data?
Every Question needs an acceptedAnswer, and the Q&A must be real and verifiable — fabricated answers get downweighted by ChatGPT Search / Perplexity.
See the full guide → - 02
Why is my Astro component's interactivity not working?
Components ship as zero-JS HTML by default, so an interactive one needs a client:* directive (client:load, client:visible, …). Without it the script is never bundled into the page.
See the full guide → - 03
Why is my custom Tailwind v4 brand colour not applied?
Colours must be declared in @theme (for example --color-brand). A missing @tailwindcss/vite plugin, or a leftover v3 config, makes bg-brand silently render nothing.
See the full guide →