When a Search Atlas feature stops working, shows missing or delayed data, or appears stuck, the cause almost always traces to one specific service layer. Find your symptom below — each entry states the cause and the fastest path to resolution.

## 🔧 Linkgraph (Core API)

### 🔴 OTTO Metrics Not Updating

**Cause:** Missing or broken background task (Celery — Search Atlas's asynchronous task processor).

1. Re-run the scan: in **OTTO SEO → All Sites (SEO Automation)**, find the site's row and click **Scan**.
2. Trigger a manual recalculation: click **Recalculate** in the OTTO Overview panel, or go to **OTTO → Settings → Recalculate Metrics**.
3. If the issue persists after clicking **Recalculate**, wait 15–30 minutes for background tasks to complete, then refresh the page.

### 🔴 OTTO — AI Content Generation Stuck (Permanent Spinner)

**Cause:** Celery worker crash left the generation flag uncleared (OTTO-1496, now resolved). The `ai_gen_in_progress` flag previously stayed set after a mid-generation crash, blocking new generations.

Because the fix adds an automatic TTL and cleanup task, most users will never see this spinner again. If you encounter a stuck spinner on an older generation job, use the navigate-away step below as a one-time reset while the cleanup task catches up.

- Navigate away from the OTTO content generation page (for example, go to the OTTO Overview tab), then return to the content generation view. This forces the UI to re-evaluate the generation status flag.
- Re-trigger AI content generation.
- If the spinner remains after navigating back, wait 15–30 minutes for the TTL-based cleanup task to clear the flag automatically, then refresh the page before re-triggering generation.
- If the spinner recurs after navigating away and re-triggering, contact support. The underlying bug (stuck `ai_gen_in_progress` flag) was resolved in OTTO-1496; a recurrence may indicate a new instance of the same pattern. Reference **OTTO-1496** so the support agent has context.

### 🔴 OTTO PPC — Ad Strength Data Stale or Missing

**Cause:** gRPC sync failures in `sync_ad_strength_for_account` (PPC-1813, now resolved). Ad strength and ad quality scores in OTTO PPC stopped updating for affected accounts starting March 2026.

- The backend fix has been deployed — ad strength data should now sync correctly.
- Allow up to 24 hours for scores to fully re-populate after the fix.
- If ad strength data is still stale or missing after 24 hours, contact support and reference **PPC-1813**.

### 🔴 OTTO PPC — Missing Weekly Campaign Performance Data

**Cause:** Boundary condition in the weekly sync task caused campaigns to be skipped (PPC-1781, now resolved). An exact 7-day boundary in the weekly campaign performance sync silently skipped campaigns from the previous run.

- New weekly syncs now capture all campaigns correctly.
- If you notice gaps in weekly data prior to the fix date, contact support and reference **PPC-1781** to request a backfill.

### 🔴 OTTO via Cloudflare — Special Character Encoding Corruption

**Cause:** Cloudflare script encoding bug that corrupted special characters on customer sites (SPE-666, now resolved).

1. Disengage OTTO on the affected site.
2. Confirm with Search Atlas support that the updated Cloudflare script has been deployed on the Search Atlas side.
3. Reconnect the Cloudflare integration to re-engage OTTO.

### 🔴 OTTO — Schema Markup Generation or Deploy Failure

**Cause:** The schema markup generator did not run, or browser-cached state is preventing deployment.

1. In the OTTO optimization dashboard, click the purple **Generate** button before attempting to deploy any suggested schema markup.
2. Clear your browser cache and retry the deploy.
3. If the error persists after these steps, this indicates a system-level generator failure. Open a support ticket with high priority and include the site URL and the schema type you were trying to deploy.

### 🔴 OTTO — Unwanted Text or Content Appearing on Site After OTTO Engagement

**Cause:** An active deployed OTTO fix (for example, a Heading Length fix) is inserting content into the front-end of the site.

1. Go to **OTTO → Deployments**.
2. Identify the deployed fix responsible for the unwanted text (such as a Heading Length fix matching the affected element).
3. Undeploy that specific fix to remove the injected content from the site.

### 🔴 OTTO WordPress Plugin — API Key Could Not Be Verified

**Cause:** The OTTO WordPress plugin requires **two separate credentials**. This error usually means only one was provided, or the values were entered in the wrong fields.

1. In Search Atlas, go to **Settings → API Keys** and copy your 32-character **SearchAtlas API Key**. Paste it into the **Search Atlas API Key** field in the WordPress plugin (**WordPress plugin → Search Atlas → Settings**).
2. Provide the second required credential — the OTTO project / site UUID — in its dedicated field in the plugin settings. Refer to the OTTO WordPress plugin setup documentation for the exact field name and where to copy the value from in Search Atlas.
3. Save the plugin settings. If the error persists, contact support with a screenshot of the plugin configuration screen.

### 🔴 503 / Dashboard Not Loading

**Cause:** General gateway error at the dashboard level (upstream service unavailable or temporary network issue).

1. Refresh after 30–60 seconds.
2. Retry the action.
3. If the error persists beyond 2–3 minutes, check the Search Atlas status page or contact support with a screenshot of the error.

### 🔴 Tasks Stuck / Never Complete

**Cause:** Queue mismatch or task failure. The stuck-site retry cap was increased in G3.9 — the system now makes more automatic attempts before declaring a final failure, so a task that previously appeared stuck may now self-resolve.

1. Do **not** re-trigger immediately. Wait at least 10–15 minutes without any manual intervention.
2. Avoid duplicate triggers while retries are in flight.
3. Re-trigger the action only after the task status changes to a final error state.

### 🔴 Crawl Stuck "In Progress"

**Cause:** Timeout on a large site.

1. Reset the crawl.
2. Re-run the crawl.
3. Reduce crawl scope if the site is large.

### 🔴 Jobs Stop Mid-Process

**Cause:** Memory limit exceeded (OOM — out of memory).

- Retry with a smaller operation.
- Avoid running multiple bulk-heavy actions simultaneously.

## 🔭 Site Explorer

### 🔴 Site Explorer Data Missing or Delayed (holistic\_pillars Tasks)

**Cause:** Database connection exhaustion affecting Site Explorer's `holistic_pillars` Celery tasks (SE-605, observed during the May 4 spike). Connection pool saturation caused holistic pillars tasks to fail or stall, leading to missing or delayed Site Explorer data.

1. Wait 10–15 minutes for the connection pool to recover and for queued `holistic_pillars` tasks to retry automatically.
2. Refresh the Site Explorer view to confirm whether the missing data has populated.
3. If data is still missing or delayed after 30 minutes, contact support and reference **SE-605** so the team can confirm the task state for your project.

**🎯 You now know the cause and fastest fix for the most common Search Atlas service errors. If your issue isn't listed here or persists after following these steps, contact Search Atlas support with your error details and any relevant ticket references from this guide.**