## 🔌 Search Atlas — CMS Integration Issues

This article covers content sync, authentication, image handling, and field mapping for **WordPress, Shopify, Drupal, and Contentful** integrations.

---

### ⚠️ Error 1: Content isn't syncing to my CMS

**What's happening:** The CMS connection may have lapsed or the connected user account lacks publishing permissions.

**Steps to try:**

1. Check connection status: *Top-right Corner Avatar → Settings → CMS Connectors → [Your CMS Domain] → Connection Status*. Reconnect if it shows Disconnected.
2. Confirm the connected account has the right role:

   - **WordPress:** Administrator (Editor and Author accounts cannot connect the plugin)
   - **Shopify:** App must have `write_content` permission — reinstall the app if needed
   - **Drupal:** User must have content creation and publishing permissions
   - **Contentful:** Management API Token must have content management (read/write) scope on the target space and environment
3. Test a single article manual sync before attempting bulk sync.
4. After reconnecting, wait 5 minutes before syncing.
5. Contact support with the CMS type, error message, and article title.

---

### 🖼️ Error 2: Images appear broken in the CMS after syncing

**What's happening:** Image URLs are relative or in a format the target CMS doesn't support.

**Steps to try:**

1. Ensure all images in your Search Atlas content use full absolute URLs starting with `https://`.
2. **Shopify:** Convert WebP images to JPEG or PNG — older Shopify themes don't support WebP.
3. **WordPress:** Resize images over 8MB before syncing — that's the WordPress default upload limit.
4. Upload images directly to the Search Atlas media library first, then reference them from there.
5. Contact support with the image URL and CMS type, plus a screenshot of the broken image.

---

### 🚫 Error 3: Shopify sync returns 'Forbidden' or 'Permission Denied'

**What's happening:** The Search Atlas Shopify app needs to be reinstalled to refresh permissions.

**Steps to try:**

1. Reinstall the Search Atlas Shopify app from the Shopify App Store — this is the most reliable fix.
2. After reinstalling, go to *Top-right Corner Avatar → Settings → CMS Connectors → [Your CMS] → Shopify → Reconnect*.
3. In *Shopify Admin → Apps → [Search Atlas App] → Permissions*, confirm `write_content` is listed.
4. Wait 5 minutes after reinstalling before attempting a sync.
5. Contact support with your Shopify store URL and the exact error from the sync log.

---

### 🔄 Error 4: Direct CMS edits are being overwritten by Search Atlas syncs

**What's happening:** Search Atlas is configured as the primary editor — syncs overwrite CMS versions.

**Steps to try:**

1. Make all edits in Search Atlas Content Assistant, then sync — treat Search Atlas as your primary editor.
2. Look for a *Sync Lock* or *Exclude from Sync* option in the article settings to protect specific articles.
3. Pause auto-sync while editing in the CMS: *Top-right Corner Avatar → Settings → CMS Connectors → [Your CMS Domain] → Disconnect*.
4. Contact support to ask about enabling 'CMS as source of truth' mode if you primarily edit in your CMS.

---

### 📝 Error 5: Formatting (headings, bold, lists) is stripped after syncing in WordPress

**What's happening:** The content format setting may be set to Plain Text instead of HTML.

**Steps to try:**

1. For WordPress Gutenberg: try enabling 'Classic Block' format in sync settings.
2. Verify the content format is set to HTML, not Plain Text.
3. Re-sync the affected article and inspect the output in the WordPress block editor.

---

### 🔑 Error 6: Contentful connector fails with 'Invalid or expired Management API Token'

**What's happening:** Previously, a backend bug (internal ref: **CG-1641**) caused the Contentful connector to reject valid Management API Tokens with an 'Invalid or expired Management API Token' error during setup. **This bug has been resolved by the engineering team** and the connector is now working as expected.

**Steps to try:**

1. Retry connecting Contentful: *Top-right Corner Avatar → Settings → CMS Connectors → Contentful → Connect*. If you previously created a failed connection, remove it first and start fresh.
2. Generate (or reuse) a **Contentful Management API Token** from *Contentful → Settings → API keys → Content management tokens*. Personal Access Tokens or Content Delivery API keys will not work.
3. Ensure the token has access to the correct Space and Environment you intend to sync to, and that the token has not been revoked.
4. Paste the token into Search Atlas and complete the Space/Environment selection.
5. Run a single-article test sync before attempting bulk syncs.
6. If you still see 'Invalid or expired Management API Token' after the fix, contact support with: your Contentful Space ID, Environment, the timestamp of the failed attempt, and confirmation that the token was generated as a Content Management token.

*Note: If you opened a ticket about this error prior to the fix, please retry the connection — no further action is required from the Search Atlas side.*