Skip to main content

SearchAtlas Sitemap Troubleshooting SOP

Overview​

  • What: Diagnose and fix the failure mode where the SearchAtlas (MetaSync) WordPress plugin dashboard reports the XML sitemap as "Generated" but the public sitemap URL (typically /sitemap_index.xml) returns a WordPress 404.
  • When: Triggered by either (a) the post-generation curl check in seo-one-time-setup.md Component 5, or (b) the SEO-and-analytics row in wordpress-post-go-live-validation-checklist.md, or (c) a Google Search Console error reporting the sitemap as unreachable.
  • Who: Onboarding specialist, SEO technician, or implementation lead. Requires WordPress admin access and SearchAtlas agency dashboard access.
  • Time Required: 5–20 minutes depending on which step resolves the issue.

Prerequisites​

  • WordPress admin access to the affected site (path: <domain>/wp-admin).
  • SearchAtlas agency dashboard access (path: https://dashboard.searchatlas.com).
  • A terminal with curl available.
  • The site has the SearchAtlas MetaSync plugin installed and OTTO marked Active. (If those aren't true, run seo-one-time-setup.md first — this SOP doesn't cover plugin install.)

Diagnostic signal (the x-metasync-otto-* response headers)​

The MetaSync plugin emits two custom HTTP headers on every response it owns. These headers are the primary diagnostic — they reveal what's broken without dashboard access.

HeaderHealthy valueFailure valuesMeaning
x-metasync-otto-cacheHIT or MISSAPI_ERRORResult of the plugin's fetch from OTTO's backend API. API_ERROR = the fetch failed (auth, endpoint, or backend issue).
x-metasync-otto-methodAPI, VIRTUAL, FILE, or CACHENONEHow the plugin chose to serve the response. NONE = no method matched; the plugin handed control back to WordPress, which returns 404.

A healthy sitemap response looks like:

HTTP/2 200
content-type: application/xml
x-metasync-otto-cache: HIT
x-metasync-otto-method: API

The failure mode this SOP fixes looks like:

HTTP/2 404
content-type: text/html; charset=UTF-8
x-metasync-otto-cache: API_ERROR
x-metasync-otto-method: NONE

Run the baseline curl as your starting point on every diagnostic:

curl -I https://<domain>/sitemap_index.xml

After each fix step below, re-run this curl. Stop when both headers change to healthy values and the status is 200.

Procedure​

Step 0 — Confirm plugin authentication state (skips Step 3 if healthy)​

WP Admin → Search Atlas → Settings → Connection & Authentication (expand).

Check the Search Atlas API Key field. If it shows ✓ Synced with a recent "last sync" timestamp ("X minutes ago"), the plugin's auth is healthy and API_ERROR is NOT caused by stale tokens. Skip Step 3 in this case — re-authenticating a healthy connection wastes time and can interrupt OTTO's heartbeat.

If the field shows red / "Disconnect Account" only / no recent sync → auth is broken and Step 3 is the most likely fix.

Step 1 — Check the plugin's sitemap serve-method setting​

WP Admin → Search Atlas → XML Sitemap → Advanced Settings (or Settings depending on plugin version).

Look for a setting controlling how the sitemap is served. Labels vary by plugin version: "Sitemap delivery method", "Output method", "Serve sitemap via", or "Sitemap source". If the value is NONE / Disabled / Off, change it to the active option (typically API or Virtual).

Click Generate Sitemap Now (bottom of the XML Sitemap page).

Re-curl. Expected change: x-metasync-otto-method moves from NONE to a real value (API / VIRTUAL / FILE). If status is still 404, continue.

Step 2 — Check OTTO Server-Side Rendering settings​

WP Admin → Search Atlas → Settings → OTTO Server-Side Rendering (expand).

Sitemap delivery on Pro/Enterprise sites typically routes through OTTO's SSR layer. A misconfiguration here (SSR disabled, wrong endpoint, content-type filter excluding XML) can produce API_ERROR even though general auth is healthy.

Confirm:

  • OTTO SSR is enabled
  • XML / sitemap content types are not excluded from SSR
  • The SSR endpoint URL (if exposed) is correct

Re-curl. If still failing, continue.

Step 3 — Re-authenticate the plugin to SearchAtlas (only if Step 0 showed broken auth)​

Skip this step if Step 0 confirmed ✓ Synced with a recent timestamp. Re-authenticating a healthy connection is unnecessary and disrupts OTTO's heartbeat.

If auth is broken: WP Admin → Search Atlas → Settings → Connection & Authentication → Re-authenticate with Search Atlas (or Disconnect then reconnect). Use the SearchAtlas agency credentials.

Re-curl. Expected change: x-metasync-otto-cache moves from API_ERROR to MISS then HIT. If still API_ERROR, continue.

Step 4 — Verify sitemap delivery is enabled at the OTTO project level​

Open the SearchAtlas dashboard → OTTO → the affected site's project → confirm sitemap output is enabled at the OTTO side (the plugin-side activation in Step 1 doesn't necessarily mean OTTO is producing the data).

The "OTTO Active" panel in the WP plugin shows checks for schema / meta / internal-linking but does not include a sitemap status item — sitemap delivery is a separate OTTO-side toggle. Locate it and ensure it's on.

If the toggle was already on, click Generate Sitemap Now in the WP plugin again to force a fresh API call.

Re-curl. If still failing, continue.

Step 5 — Check Edge Cache / CDN configuration in the plugin​

WP Admin → Search Atlas → Settings → Edge Cache / CDN (expand).

The plugin has its own CDN cache-tag handling for sitemap and schema URLs. If credentials are misconfigured here, the plugin may be unable to purge stale 404s from the CDN even when it's now producing valid sitemap content.

Confirm CDN credentials are configured (or marked N/A if not using a CDN with cache tags).

Then purge the CDN cache externally:

  • GHL hosting: click the CDN Cache button visible in the WP admin top bar. Purge.
  • Cloudflare: if the cf-ray response header was present in the baseline curl (proves Cloudflare proxy is in chain), open the Cloudflare dashboard → Caching → Configuration → Custom Purge → enter the three URLs:
    • https://<domain>/sitemap_index.xml
    • https://<domain>/wp-sitemap.xml
    • https://<domain>/robots.txt

Step 6 — Update the plugin to the latest version​

WP Admin → Plugins → Search Atlas (the MetaSync plugin) → if an update is available, run it. Older versions used deprecated API endpoints that OTTO has since removed.

After update, repeat Steps 1–5 if necessary (the update can reset some settings).

Step 7 — Submit to Google Search Console​

Once the curl returns HTTP/2 200 with application/xml content-type and healthy headers, submit the sitemap URL in GSC:

GSC → Sitemaps → Add a new sitemap → enter https://<domain>/sitemap_index.xml → Submit.

Confirm GSC reports the submission as "Success" within 24 hours.

Permanent fix (canonical resolution — validated 2026-05-24)​

The durable fix is to install the Auctollo XML Sitemap Generator plugin and let it own sitemap serving. SearchAtlas stays active for everything else (OTTO + schema + Brand Vault + content optimization + indexation control); only sitemap publishing moves to Auctollo.

Why Auctollo and not the WP core sitemap: WP core's /wp-sitemap.xml was tried as the fallback first. It worked briefly but was not durable — MetaSync's URL claims periodically re-asserted (one observed regression within 18 hours on symphonycore.com), requiring repeated manual intervention. Auctollo wins the URL routing battle against MetaSync via higher hook priority and serves its XSL stylesheet from its own plugin directory (bypassing MetaSync's .xsl URL hijack entirely).

Follow the dedicated SOP​

Auctollo XML Sitemap Plugin Setup SOP — 10–15 minute procedure. Install, configure (sitemap content selection aligned with Indexation Control), delete the physical robots.txt (silent-failure check — see section below), curl verification, GSC submission, cleanup of stale GSC entries.

After the Auctollo SOP completes, the curl signal flips: /sitemap.xml returns HTTP 200 with content-type: text/xml. The response may still carry MetaSync's x-metasync-otto-cache: API_ERROR headers as a side effect of MetaSync's filter still running — that's cosmetic noise; Auctollo's content is what's served.

What this SOP retains​

Steps 0–7 above remain useful for diagnostic purposes — they identify whether the failure is auth, OTTO project, plugin version, or CDN-related. If the Auctollo install doesn't resolve the issue, those steps narrow down where the problem actually lives. But for production fix on an affected client, jump straight to the Auctollo SOP.

Silent failure: physical robots.txt overrides plugin-managed robots.txt​

A common GHL-hosted WP failure mode where SearchAtlas's "robots.txt file saved successfully!" banner is misleading — the save reaches SA's database option but a physical robots.txt file in the web root is being served directly by nginx, never reaching WP / SA's dynamic handler. Every edit you make in SA is silently ignored at serve time.

Detection​

Response headers on /robots.txt show static-file fingerprints:

curl -I https://<domain>/robots.txt

Static-file fingerprints (physical file is overriding):

  • accept-ranges: bytes — nginx serves real files with range-request support; dynamic PHP usually doesn't advertise this
  • content-length: set on response
  • No WP-style headers (no link: <.../wp-json/>, no x-wp-*, no x-metasync-*)
  • cache-control: max-age=86400 or similar long TTL (typical static file)

If you also see the live body content not matching what's in SA's robots.txt editor → physical file confirmed.

Fix​

WP Admin → WP File Manager (or any file manager / SFTP if available) → navigate to the web root (the directory containing wp-config.php) → look for robots.txt.

Two options:

  • Preferred: delete the physical file. SA's dynamic handler then owns the URL. Every future SA robots.txt edit propagates immediately (after CDN purge).
  • Acceptable: overwrite the physical file's contents to match SA's editor. Works for the immediate fix but every future SA edit also requires editing the physical file — silent failure resumes if forgotten.

After deletion/overwrite: purge CDN cache for /robots.txt, then re-curl and verify content matches.

Prevention for new clients​

During seo-one-time-setup.md Component 5, check for the physical robots.txt file FIRST. If present, delete it before relying on SA's robots.txt editor. Otherwise the editor will appear to work but won't actually propagate.

Verification​

The SOP is complete when all of the following hold:

  • curl -I https://<domain>/sitemap_index.xml returns HTTP/2 200
  • Response content-type is application/xml (or text/xml)
  • x-metasync-otto-cache is HIT or MISS (not API_ERROR)
  • x-metasync-otto-method is a real value (not NONE)
  • Google Search Console reports the sitemap as ingested with no errors
  • If migrating from another sitemap plugin: old sitemap URLs (e.g., /sitemap.xml, /wp-sitemap.xml) either resolve to a working sitemap or 301-redirect to /sitemap_index.xml

Escalation​

If all 6 steps above are completed and the curl still returns HTTP/2 404 with x-metasync-otto-cache: API_ERROR, the issue is on SearchAtlas's backend side, not the WordPress side. Open a support ticket with SearchAtlas including:

  • The full curl headers from the failing request
  • The OTTO project ID for the affected site
  • A timestamp range showing when API_ERROR started appearing
  • Confirmation that the plugin has been re-authenticated and updated to the latest version

Pending vendor response, leave the GSC sitemap submission pending — do not submit a 404 URL.

  • One-Time SEO Setup — upstream; Component 5 references this SOP if the post-generation curl check fails
  • WordPress Post-Go-Live Validation Checklist — references this SOP from the SEO-and-analytics row
  • SearchAtlas WordPress Schema Markup Reference — documents the x-metasync-otto-* headers and the four serve-method values
  • SearchAtlas Client Data Intake — upstream spec for what the plugin should be producing