AI Pages Troubleshooting

Having trouble with AI Pages? This page covers the most common issues and their solutions.

Installation issues

Integration not intercepting requests

Symptoms: Requests fail, no optimization happening

Causes:

1. 1Integration not deployed or not active
2. 2Routing not configured correctly
3. 3Integration not running before your app's route handlers

Solutions:

• Cloudflare: Verify your Worker exists in Workers & Pages and the route matches your domain (\*yourdomain.com/*\)
• Vercel/Next.js: Verify \middleware.ts\ is at the project root (next to \package.json\) and deployed
• Netlify: Verify the edge function exists and is registered in \netlify.toml\
• WordPress: Verify \trakkr-prism.php\ is in \wp-content/mu-plugins/\ and shows in Admin → Plugins → Must-Use
• Node.js: Verify the middleware is registered with \app.use()\ before your route handlers
• Nginx: Verify \nginx -t\ passes and you've reloaded after changes

"API key invalid" error

Symptoms: Integration deploys but returns 401 errors

Causes:

1. 1Incorrect API key in integration code
2. 2API key was regenerated but integration not updated
3. 3Typo in the API key

Solutions:

1. 1Go to Trakkr → AI Pages → copy your current API key
2. 2Update your integration code with the new key
3. 3Redeploy your integration

"Site not loading" after setup

Symptoms: Website returns errors for all visitors

Causes:

1. 1Syntax error in integration code
2. 2Integration crashing on every request
3. 3Platform misconfiguration

Quick fix: Remove or disable the AI Pages integration. This instantly restores normal operation.

Then investigate:

1. 1Check your platform's logs for errors
2. 2Verify integration code was copied correctly
3. 3Test with a fresh deployment

Optimization issues

Pages not being optimized

Symptoms: AI crawlers get normal (un-optimized) pages

Diagnostic steps:

1. 1Test manually:

curl -A "GPTBot" https://yourdomain.com/ | head -100

1. 1Check for AI Pages headers in response:

X-Prism-Cache: HIT (or MISS)

Common causes:

• Path is filtered - URLs like \/api/*\, \/admin/*\ are skipped by default
• File extension filtered - \.js\, \.css\, images are skipped
• Usage limit reached - Check AI Pages → Usage

Solutions:

• Verify the path should be optimized
• Check your usage hasn't exceeded limits
• Review your platform's logs for errors

Optimization looks wrong or incomplete

Symptoms: Optimized content missing sections, broken formatting

Causes:

1. 1Page relies heavily on JavaScript that didn't render
2. 2Content loads asynchronously after initial render
3. 3Page has anti-bot protections

Solutions:

1. 1Test your page - Go to AI Pages → Cache → Test AI Pages, enter your URL
2. 2Check rendering - Compare original vs optimized in the test tool
3. 3Simplify problem pages - Ensure critical content is in initial HTML

Cache not updating

Symptoms: Old content being served to crawlers

Cause: Cache TTL is 7 days

Solution: Wait for cache to expire, or contact support for manual cache clear (coming soon as self-service feature)

Analytics issues

No crawler visits showing

Symptoms: Analytics empty even after setup

Causes:

1. 1No real AI crawlers have visited yet (normal)
2. 2Worker not forwarding to AI Pages API
3. 3Analytics not loading properly

Solutions:

1. 1Test manually - Run a curl test, it should appear in analytics
2. 2Wait - Real crawler visits may take 24-48 hours
3. 3Verify setup - Re-run the installation verification steps

Usage seems high

Symptoms: Using more requests than expected

Causes:

1. 1High crawler traffic (good problem to have!)
2. 2Same pages being recrawled frequently
3. 3Cache misses causing re-optimization

Solutions:

1. 1Check AI Pages → Analytics → Top Pages to see what's being crawled
2. 2Verify cache hit rate is healthy (should be 70%+)
3. 3Consider if usage matches your site's AI visibility

Platform-specific issues

Timeout errors

Symptoms: 524 or timeout errors in logs

Cause: Integration taking too long to get a response from the API

Solutions:

1. 1Check that the timeout in your integration code is set to at least 1500ms
2. 2Origin server may be slow — check your hosting performance
3. 3Very large pages may need special handling — contact support

Rate limit errors

Symptoms: 429 errors from your platform

Cause: Exceeded your platform's request limits

Solutions:

• Cloudflare: Upgrade to Workers Paid ($5/month) if exceeding 100K requests/day
• AWS Lambda@Edge: Check your Lambda concurrency limits
• Other platforms: Check your plan's edge function or middleware limits

Frequently asked questions

Does AI Pages affect my SEO?

No. AI Pages never serves different content to search engine crawlers (Googlebot, Bingbot). Only AI crawlers (GPTBot, ClaudeBot, etc.) receive optimized content.

Can I use AI Pages with any hosting platform?

Yes. AI Pages supports 9 platforms natively: Cloudflare, Vercel, Netlify, Next.js, AWS CloudFront, WordPress, Node.js, and Nginx. For platforms without native support (Shopify, Squarespace, Wix, Webflow, etc.), you can use Cloudflare as a free DNS proxy in front of your site.

Is this cloaking? Will I be penalized?

No, this is not cloaking. Cloaking means showing search engines different content to manipulate rankings. AI Pages:

1. 1Doesn't affect search engine crawlers at all
2. 2Shows AI crawlers the same content, just formatted for machine readability
3. 3Is equivalent to providing a mobile-optimized version of your site

How long until I see visibility improvements?

Varies by AI model:

• Perplexity: Hours to days (uses real-time search)
• ChatGPT: Days to weeks (model updates)
• Claude: Weeks to months (training cycles)

Be patient. AI model updates aren't instant.

Can I see what AI Pages serves to crawlers?

Yes! Go to AI Pages → Cache → Test AI Pages. Enter any URL to see:

• Original HTML
• AI Pages-optimized HTML
• What changed

Will AI Pages slow down my site for human visitors?

No. Human visitors add <10ms latency (imperceptible). The integration quickly checks the user-agent and passes human traffic through unchanged.

What if an AI crawler visits while my site is down?

The crawler will receive an error, and AI Pages won't cache anything. When your site recovers, the next crawler visit will trigger normal optimization.

Can I disable AI Pages for specific pages?

Yes. You can configure exclude rules in AI Pages → Settings → Rules. Add paths like \/admin/*\ or \/checkout/*\ to skip optimization.

Getting help

If you're still stuck:

Contact support

Email [email protected] with:

• Your domain
• Which platform you're using
• What you've tried
• Screenshots of any errors

Check status

Visit trakkr.ai/status to check if there's a known outage.

Community

Join our Slack community to ask questions and share tips with other AI Pages users.

Next steps