Troubleshooting Guide

Fresh

Common issues with AI visibility and their solutions. Use this guide when things aren't working as expected.

Quick Diagnosis

┌─────────────────────────────────────────────────────────────────────┐
│                    TROUBLESHOOTING FLOWCHART                         │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│   Problem: AI doesn't mention your brand                            │
│                                                                      │
│   ┌─────────────┐                                                   │
│   │ Can AI bots │──No──► Fix robots.txt (Issue #1)                 │
│   │ crawl you?  │                                                   │
│   └──────┬──────┘                                                   │
│          │Yes                                                       │
│          ▼                                                          │
│   ┌─────────────┐                                                   │
│   │ Is content  │──No──► Fix JavaScript (Issue #2)                 │
│   │ in HTML?    │                                                   │
│   └──────┬──────┘                                                   │
│          │Yes                                                       │
│          ▼                                                          │
│   ┌─────────────┐                                                   │
│   │ Do you have │──No──► Build entity presence (Issue #5)          │
│   │ KG presence?│                                                   │
│   └──────┬──────┘                                                   │
│          │Yes                                                       │
│          ▼                                                          │
│   Content quality/authority issue (Issues #6-8)                     │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

Issue #1: AI Bots Blocked

Symptoms

• Not appearing in AI search results
• No AI crawler traffic in logs
• AI platforms return no information about you

Diagnosis

# Check robots.txt
curl https://yoursite.com/robots.txt

# Look for blocks like:
User-agent: GPTBot
Disallow: /

# Or blanket blocks:
User-agent: *
Disallow: /

Solution

Update robots.txt to allow AI crawlers:

# Allow AI crawlers
User-agent: GPTBot
Allow: /

User-agent: PerplexityBot
Allow: /

User-agent: anthropic-ai
Allow: /

User-agent: Google-Extended
Allow: /

User-agent: CCBot
Allow: /

→ Reference: SOP 008 - AI Bot Access

---

Issue #2: JavaScript-Dependent Content

Symptoms

• Content visible in browser but not to crawlers
• "Page source" shows empty or minimal content
• AI returns outdated or no information

Diagnosis

1. Disable JavaScript in browser
2. Visit your page
3. Check if main content is visible

Or:

# Fetch as a basic crawler
curl https://yoursite.com/page
# Check if content is in response

Solution

1. Implement server-side rendering (SSR)
2. Use static site generation where possible
3. Pre-render critical content

For React/Next.js:

// Use getServerSideProps or getStaticProps
export async function getStaticProps() {
  // Fetch data at build time
}

---

Issue #3: AI Returns Wrong Information

Symptoms

• AI provides incorrect facts about your brand
• Outdated information in responses
• Confusion with similarly-named entities

Diagnosis

1. Query AI: "What is [Your Brand]?"
2. Note incorrect claims
3. Identify the source of confusion

Solution

For outdated info:

• Update content with current information
• Add dateModified to schema
• Ensure content is crawlable

For entity confusion:

• Clarify your entity in content: "Acme Corp, the software company founded in 2015..."
• Build stronger knowledge graph presence
• Use consistent naming everywhere

For factual errors:

• Create authoritative content that contradicts the error
• Build more citations from trusted sources
• Strengthen E-E-A-T signals

→ Reference: SOP 005 - Knowledge Graph Presence

---

Issue #4: Not Being Cited

Symptoms

• AI answers questions in your area but doesn't cite you
• Competitors are cited instead
• Your content seems invisible

Diagnosis

• Run queries on your topics
• Note who IS being cited
• Analyze what they have that you don't

Solution

1. Improve content structure

   • Clear headings matching queries
   • 100-300 token paragraphs
   • Declarative statements

2. Build authority signals

   • Knowledge graph presence
   • Author identity
   • Schema markup

3. Create citation-worthy content

   • Original research
   • Definitive answers
   • Unique data

→ Reference: WF-001 - GenAI Content Optimization

---

Issue #5: No Entity Recognition

Symptoms

• AI says "I don't have information about [Brand]"
• Confused with other entities
• Generic or vague responses

Diagnosis

Query: "What is [Your Brand]?"

If AI doesn't recognize you:

• No knowledge graph presence
• Weak or missing schema
• Low authority signals

Solution

1. Create Wikidata entry

   • Go to wikidata.org
   • Create item with all relevant properties
   • Add identifiers

2. Claim other profiles

   • Google Knowledge Panel
   • Crunchbase
   • LinkedIn

3. Implement schema

   • Organization schema
   • sameAs linking all profiles

→ Reference: WF-002 - Machine Trust Building

---

Issue #6: Poor Chunk Retrieval

Symptoms

• AI includes your content but misses key points
• Answers are incomplete
• Context is lost

Diagnosis

• Review your content structure
• Check paragraph lengths
• Look for mixed topics in single blocks

Solution

1. Restructure content

   • One idea per paragraph
   • 100-300 tokens per block
   • Clear headings

2. Keep context together

   • Claims with evidence in same chunk
   • No orphan pronouns

3. Add semantic redundancy

   • Rephrase key ideas
   • Use synonyms

→ Reference: SOP 001 - Content Chunking

---

Issue #7: Schema Not Working

Symptoms

• No rich results in Google
• Structured data errors
• AI not recognizing structured info

Diagnosis

1. Test with Google Rich Results Test
2. Check for errors/warnings
3. Verify schema is in page source

Solution

For syntax errors:

• Use schema generator tool
• Validate JSON-LD
• Fix nesting issues

For missing schema:

{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Your Company",
  "url": "https://yoursite.com",
  "sameAs": [
    "https://linkedin.com/company/...",
    "https://twitter.com/..."
  ]
}

For schema not appearing:

• Check JavaScript rendering
• Ensure schema is in HTML source
• Verify it loads before crawl timeout

→ Reference: SOP 003 - Schema Markup

---

Issue #8: Slow Page Load Affecting Crawl

Symptoms

• Incomplete crawling
• Timeout errors in logs
• Partial content retrieval

Diagnosis

• Check PageSpeed Insights score
• Review server response time
• Check for large assets

Solution

1. Improve server response

   • Upgrade hosting
   • Implement caching
   • Use CDN

2. Optimize assets

   • Compress images
   • Minify CSS/JS
   • Lazy load non-critical content

3. Target metrics

   • Load time: ❤️ seconds
   • Server response: <200ms
   • Core Web Vitals: Pass

---

Quick Fixes Checklist

When something isn't working:

• [ ] robots.txt allows AI bots
• [ ] Content visible without JavaScript
• [ ] Schema validates without errors
• [ ] Page loads in ❤️ seconds
• [ ] Entity name is consistent everywhere
• [ ] Knowledge graph entries exist
• [ ] Author identity is clear
• [ ] Content is chunked properly

When to Escalate

If after fixing all above issues you still have problems:

1. Check if it's a timing issue - Changes take time to propagate
2. Review competitor approach - What are they doing differently?
3. Consider content quality - Is your content truly authoritative?
4. Test on different platforms - Issue might be platform-specific

See Also

• WF-003 - AI Visibility Audit
• Tool Stack
• SOP 004 - AI-Crawlable Sites