> ## Documentation Index
> Fetch the complete documentation index at: https://docs.searchable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Solutions to common issues and problems in Searchable

## Common Issues

Quick solutions to the most frequent problems users encounter.

<AccordionGroup>
  <Accordion title="Zero visibility scores / No brand mentions" icon="chart-line-down">
    ### Problem

    Your prompts show 0% mention rate and AI models never cite your brand.

    ### Causes

    * Brand is too new or unknown
    * No comprehensive content about your products/services
    * Missing structured data and schema markup
    * Low domain authority

    ### Solutions

    <Steps>
      <Step title="Create Foundational Content">
        Write comprehensive articles about:

        * What your product/service is
        * How it works
        * Key features and benefits
        * Use cases and examples
      </Step>

      <Step title="Implement Structured Data">
        Add schema markup:

        * Organization schema with logo and description
        * Product/Service schemas
        * FAQ schema
        * Article schema on blog posts
      </Step>

      <Step title="Build Citation Authority">
        * Get mentioned in industry publications
        * Earn backlinks from authoritative sites
        * Create original research and data
        * Establish thought leadership
      </Step>

      <Step title="Start with Easier Prompts">
        Begin with brand-specific prompts like:

        * "What is \[Your Brand]?"
        * "Tell me about \[Your Company]"

        Then expand to category queries.
      </Step>

      <Step title="Be Patient">
        AI model training updates take time. Allow 4-8 weeks for improvements to show in visibility tracking.
      </Step>
    </Steps>

    <Warning>
      If you have zero mentions after 3 months of optimization, contact support for a strategy review.
    </Warning>
  </Accordion>

  <Accordion title="Audit not starting or timing out" icon="clock">
    ### Problem

    Audits get stuck or time out without completing.

    ### Causes

    * Large site with many pages
    * Slow server response times
    * Robots.txt blocking Searchable's crawler
    * Firewall or security blocking our IP addresses

    ### Solutions

    <Steps>
      <Step title="Check Robots.txt">
        Ensure Searchable's user agent is allowed:

        ```text theme={null}
        User-agent: SearchableBot
        Allow: /
        ```
      </Step>

      <Step title="Verify Server Performance">
        * Check your server response times
        * Ensure your site isn't down or overloaded
        * Contact your hosting provider if needed
      </Step>

      <Step title="Reduce Scope">
        * Limit audit to fewer pages
        * Start with your most important pages
        * Gradually expand scope
      </Step>

      <Step title="Whitelist Searchable IPs">
        If you have firewall rules, whitelist our crawler IPs (available in Settings → Security)
      </Step>

      <Step title="Contact Support">
        If issues persist after these steps, contact support with:

        * Your project ID
        * The timestamp of failed audits
        * Any error messages
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Integration connection failures" icon="plug">
    ### Problem

    Unable to connect Google Search Console, Google Analytics, or CMS integrations.

    ### Solutions by Integration

    **Google Search Console:**

    * Ensure you have Owner or Full User permission in GSC
    * Verify the property is verified in GSC
    * Use the same Google account for both GSC and Searchable
    * Try disconnecting and reconnecting
    * Clear browser cache and cookies

    **Google Analytics 4:**

    * Confirm you have at least Editor access to the GA4 property
    * Ensure GA4 property is active (not archived)
    * Check that data is flowing into GA4
    * Verify you're selecting the correct property/stream

    <Tip>
      Most integration issues are resolved by disconnecting, clearing cache, and reconnecting with fresh credentials.
    </Tip>
  </Accordion>

  <Accordion title="Scores dropped suddenly" icon="arrow-trend-down">
    ### Problem

    Your scores decreased significantly without any changes on your end.

    ### Possible Causes

    * Competitors improved (relative scoring)
    * New technical issues detected
    * Third-party scripts causing slowdowns
    * Server performance degradation
    * Algorithm updates in scoring model

    ### Investigation Steps

    <Steps>
      <Step title="Check Recent Changes">
        Review any recent updates to:

        * Your website
        * Hosting environment
        * Third-party integrations
        * Content changes
      </Step>

      <Step title="Review New Issues">
        Go to Issues tab and look for:

        * New critical or high-priority issues
        * Recently detected problems
        * Issues affecting multiple pages
      </Step>

      <Step title="Compare Audits">
        Use audit history to compare:

        * Before and after scores
        * New issues that appeared
        * Changes in specific metrics
      </Step>

      <Step title="Check Server Performance">
        * Run PageSpeed Insights
        * Check Core Web Vitals
        * Test server response time
        * Monitor uptime
      </Step>

      <Step title="Review Competitors">
        If you track competitors, check if they improved significantly
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Pages not being discovered" icon="sitemap">
    ### Problem

    Some of your pages aren't showing up in the monitored pages list.

    ### Causes

    * Pages not linked from homepage
    * Blocked by robots.txt or noindex
    * Sitemap is not available or not up to date
    * Behind authentication
    * JavaScript-rendered content
    * Crawl depth limit reached

    ### Solutions

    <Steps>
      <Step title="Check Internal Linking">
        Ensure pages are linked from your homepage or sitemap within 3 clicks
      </Step>

      <Step title="Verify Indexability">
        Check that pages:

        * Don't have noindex tags
        * Aren't blocked in robots.txt
        * Return 200 status codes
        * Don't require login
      </Step>

      <Step title="Add Pages Manually">
        Go to Pages → Add Page and enter specific URLs you want to monitor
      </Step>

      <Step title="Adjust Crawl Settings">
        In Settings → Crawl Configuration:

        * Increase crawl depth
        * Adjust included/excluded patterns
        * Enable JavaScript rendering if needed
      </Step>

      <Step title="Submit Sitemap">
        * Ensure you have an XML sitemap
        * Submit it in project settings
        * Verify sitemap is accessible
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Slow dashboard loading" icon="gauge-simple">
    ### Problem

    Dashboard takes a long time to load or feels sluggish.

    ### Quick Fixes

    * **Reduce date range**: Shorter time periods load faster
    * **Limit pages**: Monitor fewer pages
    * **Clear filters**: Reset any active filters
    * **Clear browser cache**: Force refresh (Ctrl+F5 or Cmd+Shift+R)
    * **Use modern browser**: Chrome, Firefox, or Edge latest versions
    * **Check internet connection**: Ensure stable, fast connection

    ### If Problems Persist

    * Try incognito/private mode
    * Disable browser extensions
    * Check browser console for errors (F12)
    * Contact support with browser and network details
  </Accordion>

  <Accordion title="API errors or rate limits" icon="code">
    ### Problem

    Getting 429 (Too Many Requests) or other API errors.

    ### Solutions

    **Plan availability:** API keys are included with Custom contracts. Starter, Professional, and Agency accounts rely on in-platform workflows and cannot generate API keys.

    **If you have Custom access:**

    1. Go to Settings → API to confirm credentials and observe usage
    2. Review which endpoints are consuming quota and adjust batching or caching
    3. Reach out to your success manager for temporary limit increases when needed

    **Reduce Usage:**

    * Implement caching on your end
    * Batch requests where possible
    * Optimize polling frequency

    **API Error Codes:**

    * 401: Invalid or expired API key
    * 403: Insufficient permissions
    * 404: Resource not found
    * 429: Rate limit exceeded
    * 500: Server error (contact support)

    <CodeGroup>
      ```bash Example: Check API Status theme={null}
      curl -H "Authorization: Bearer YOUR_API_KEY" \
        https://api.searchable.com/v1/status
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Billing and subscription issues" icon="credit-card">
    ### Problem

    Payment failed, subscription cancelled, or billing questions.

    ### Common Issues

    **Payment Failed:**

    * Update payment method in Settings → Billing
    * Check card hasn't expired
    * Verify sufficient funds
    * Contact bank if card is being declined

    **Subscription Not Active:**

    * Check email for failed payment notices
    * Verify billing cycle and renewal date
    * Contact support if charged but not upgraded

    **Upgrade Not Applied:**

    * Upgrades are immediate
    * Try logging out and back in
    * Clear browser cache
    * Check confirmation email

    **Downgrade Questions:**

    * Downgrades apply at end of billing period
    * Data preserved for 30 days
    * Can re-upgrade anytime

    **Refunds:**

    * Contact support within 14 days
    * Must not have exceeded usage limits
    * One-time courtesy refunds available
  </Accordion>

  <Accordion title="Team member access problems" icon="users">
    ### Problem

    Team members can't access project or see incorrect data.

    ### Solutions

    **Member Can't See Project:**

    * Verify invitation was sent and accepted
    * Check email spam folder for invitation
    * Resend invitation from Settings → Team
    * Ensure correct email address was used

    **Wrong Permissions:**

    * Review role assignments (Admin, Editor, Viewer)
    * Update roles in Settings → Team → Manage
    * Remember: changes take effect immediately

    **SSO Issues (Custom):**

    * Verify SSO is configured correctly
    * Check user is in correct organization
    * Test with different user
    * Review audit logs

    <Info>
      Team features are available on Professional, Agency, and Custom plans only.
    </Info>
  </Accordion>
</AccordionGroup>

## Getting Additional Help

### Support Resources

<CardGroup cols={2}>
  <Card title="Documentation" icon="book" href="/introduction">
    Browse all documentation
  </Card>

  <Card title="Email Support" icon="envelope" href="mailto:support@searchable.com">
    [support@searchable.com](mailto:support@searchable.com)
  </Card>

  <Card title="Join Our Slack" icon="comments" href="https://join.slack.com/t/searchablecommunity/shared_invite/zt-3d72toig3-5CNPzd1ujFQu_IanWGTHDA">
    Ask the community
  </Card>

  <Card title="Status Page" icon="signal" href="https://status.searchable.com">
    Check system status
  </Card>
</CardGroup>

### Response Times

* **Starter**: Email support, 2-3 business days
* **Professional**: Priority support, 24-hour response
* **Agency**: Dedicated success manager with same-business-day replies
* **Custom**: SLA-backed support with contracted response times

### When Contacting Support

Include these details for faster resolution:

<Check>Project ID (found in Settings)</Check>
<Check>What you were trying to do</Check>
<Check>Steps to reproduce the problem</Check>
<Check>Screenshots or error messages</Check>
<Check>Browser and OS version</Check>
<Check>When the problem started</Check>

## Feature Requests

Have an idea for improving Searchable?

1. **Check Existing Requests**: Visit our [Feature Request Board](https://features.searchable.com)
2. **Vote on Requests**: Upvote features you want
3. **Submit New Ideas**: Create new feature requests
4. **Track Progress**: See what's in development

Popular requests get prioritized!

## Report a Bug

Found a bug?

1. Go to Settings → Help → Report Bug
2. Describe the bug in detail
3. Include steps to reproduce
4. Attach screenshots if helpful
5. Note your environment (browser, OS, plan)

We aim to fix critical bugs within 24-48 hours.

## Emergency Support

For critical production issues affecting your business:

**Custom Customers:**

* Use the emergency line provided in your onboarding packet
* Direct access to engineering with 1-hour SLA

**Agency Customers:**

* Mark support tickets as "Urgent"
* Dedicated manager responds within the same business day

**Professional Customers:**

* Flag tickets as high priority for fastest routing
* Expect responses within 24 hours on business days

**Starter & Trial Users:**

* Join our Slack community for the quickest peer assistance
* Critical security issues are escalated immediately

## Next Steps

Still having issues?

<CardGroup cols={2}>
  <Card title="Contact Support" icon="headset" href="mailto:support@searchable.com">
    Get personalized help
  </Card>

  <Card title="Join Our Slack" icon="users" href="https://join.slack.com/t/searchablecommunity/shared_invite/zt-3d72toig3-5CNPzd1ujFQu_IanWGTHDA">
    Ask the community
  </Card>
</CardGroup>