Search Atlas Help Center

🔌 CMS Integration (WordPress, Shopify, Contentful)

Open in
View as Markdown Open in ChatGPT Open in Claude
Camilo Aponte

Camilo Aponte

Last updated on Sep 30, 2026

This article covers:

  • WordPress publishing
  • Shopify blog publishing
  • Contentful integrations
  • image synchronization
  • authentication failures
  • content type mismatches
  • CMS API permissions
  • encoding issues
  • and publish synchronization delays.

CMS publishing workflows depend on:

  • external CMS APIs
  • OAuth or application passwords
  • media accessibility
  • correct permissions
  • active content models
  • and stable synchronization between SearchAtlas and third-party platforms.

Because these workflows involve external systems, temporary delays and authorization issues are common.

⚠️ Error 1: WordPress content push failing — posts not appearing in WordPress

What's happening

The most common cause is an expired, revoked, or invalid WordPress Application Password.

Additional causes include:

  • security plugins blocking API access
  • REST API restrictions
  • incorrect user permissions
  • or WordPress caching conflicts.

Steps to try

  1. Go to:
    WordPress → Settings
  2. Generate a new Application Password in WordPress:
    Users → Your Profile → Application Passwords
  3. Update the password in Search Atlas.
  4. Confirm the connected WordPress user has Editor or Administrator permissions.
  5. Verify the WordPress REST API is publicly accessible.
  6. Disable security plugins temporarily to test connectivity.
  7. Confirm your domain uses the correct HTTPS protocol.
  8. Retry publishing a smaller test article first.
  9. Check whether WordPress caching plugins delay post visibility.
  10. Contact support if publishing still fails after reconnecting credentials.

Important Notes

  • Application Passwords can become invalid after password resets or security changes.
  • Many WordPress security plugins block external publishing by default.

⚠️ Error 2: Shopify publish rejected — "requires merchant approval for write_content scope"

What's happening

Shopify requires explicit merchant approval before apps can publish blog content.

This error appears when:

  • write_content permissions were never approved
  • permissions changed
  • or the Shopify app authorization became outdated.

Steps to try

  1. Open Shopify Admin.
  2. Go to:
    Apps → SearchAtlas App → Permissions
  3. Approve the write_content scope.
  4. Disconnect and reconnect Shopify inside SearchAtlas.
  5. Confirm you are logged in as the Shopify store owner.
  6. Verify the app still appears under active installed apps.
  7. Retry publishing after reauthorization.
  8. Test with a small draft article first.
  9. Confirm the target Shopify blog exists and is active.
  10. Contact support if permissions appear approved but publishing still fails.

Important Notes

  • Shopify permission scopes are controlled entirely by Shopify security policies.
  • Reauthorization often refreshes missing scopes automatically.

⚠️ Error 3: Article image fails Shopify validation — "image is invalid"

What's happening

Shopify rejects images when:

  • files exceed size limits
  • unsupported formats are used
  • images are corrupted
  • or source URLs are inaccessible.

Steps to try

  1. Convert images to JPG or PNG format.
  2. Keep image size under 20MB.
  3. Avoid unsupported WebP formats on older Shopify stores.
  4. Confirm image URLs load publicly in-browser.
  5. Replace externally blocked image URLs.
  6. Re-upload the image directly into SearchAtlas.
  7. Compress oversized images before publishing.
  8. Avoid hotlinking from restricted domains.
  9. Test publishing with a single image first.
  10. Contact support if valid images continue failing Shopify validation.

Important Notes

  • Shopify validates image accessibility before importing.
  • Publicly accessible URLs are required.

⚠️ Error 4: Contentful connection fails — "Space endpoint not found"

What's happening

This error occurs when:

  • the Space ID is incorrect
  • the API token is invalid
  • the wrong API token type is used
  • or the Contentful space no longer exists.

Steps to try

  1. Go to:
    Settings → CMS Connectors (Contentful)
  2. Re-enter the correct Space ID.
  3. Generate a new Content Management API token.
  4. Confirm you are using the Management API token — not the Delivery API token.
  5. Verify the Contentful space still exists.
  6. Confirm your account has access to that space.
  7. Disconnect and reconnect Contentful integration.
  8. Retry publishing after reconnection.
  9. Test the connection with a simple content entry first.
  10. Contact support if endpoint validation still fails.

Important Notes

  • Delivery tokens cannot publish content.
  • Management tokens are required for write operations.

⚠️ Error 5: Contentful content type not found — publish fails

What's happening

Search Atlas can only publish into active Contentful content types.

Publishing fails when:

  • the content type is still draft
  • the API ID is incorrect
  • or the selected content type does not exist.

Steps to try

  1. Open Contentful → Content Model.
  2. Confirm the content type is activated and published.
  3. Verify the API ID matches exactly.
  4. Re-select the content type inside SearchAtlas.
  5. Confirm required fields exist inside the model.
  6. Ensure field validations are not blocking publishing.
  7. Test publishing a minimal content entry.
  8. Republish the content type after edits.
  9. Refresh the Contentful integration connection.
  10. Contact support if valid content types still fail recognition.

Important Notes

  • Display names and API IDs are different.
  • SearchAtlas uses the API ID internally.

⚠️ Error 6: CMS database connection refused (UCMSI service unavailable)

What's happening

The CMS Integration service occasionally restarts or temporarily loses connectivity.

This can interrupt:

  • publishing
  • synchronization
  • and API communication.

Steps to try

  1. Wait 5–10 minutes and retry.
  2. Refresh the CMS Integration dashboard.
  3. Retry publishing a small draft article.
  4. Confirm your CMS credentials are still valid.
  5. Check whether all CMS integrations are affected or only one.
  6. Disconnect and reconnect the CMS integration.
  7. Retry during off-peak hours.
  8. Save/export your content locally before retrying.
  9. Check whether the CMS itself is operational.
  10. Contact support if the service remains unavailable longer than 15 minutes.

Important Notes

  • Most UCMSI outages self-recover automatically.
  • Content is usually preserved even when publishing fails.

⚠️ Error 7: Published article contains garbled special characters

What's happening

Character encoding mismatches between:

  • SearchAtlas (UTF-8)
  • databases
  • CMS rendering engines
  • or imported legacy content

can corrupt:

  • bullets
  • apostrophes
  • em dashes
  • smart quotes
  • and accented characters.

Steps to try

  1. Confirm your CMS database uses UTF-8MB4 encoding.
  2. Verify your WordPress installation uses UTF-8MB4.
  3. Re-save the affected article manually.
  4. Avoid copy-pasting from Word documents directly.
  5. Remove malformed hidden characters before publishing.
  6. Test publishing a short clean-text article first.
  7. Disable problematic legacy plugins temporarily.
  8. Check whether the issue only affects imported content.
  9. Compare the rendered article source code.
  10. Contact support with examples of broken characters if the issue persists.

Important Notes

  • Shopify and Contentful usually handle encoding automatically.
  • Legacy WordPress databases are more prone to encoding mismatches.

⚠️ Error 8: Content pushed to CMS but images are missing

What's happening

Images referenced by inaccessible or broken URLs cannot be fetched by the CMS during publishing.

This commonly occurs when:

  • images are private
  • temporary URLs expire
  • media libraries are disconnected
  • or hotlinked assets are blocked.

Steps to try

  1. Open every image URL directly in-browser.
  2. Confirm each image loads publicly without authentication.
  3. Replace broken URLs before publishing.
  4. Upload missing images directly into your CMS media library.
  5. Avoid temporary CDN URLs.
  6. Re-upload images inside SearchAtlas.
  7. Publish a test article containing one image first.
  8. Check whether image-hosting firewalls block external requests.
  9. Verify media permissions inside Shopify or WordPress.
  10. Contact support if images consistently fail despite being publicly accessible.

Important Notes

  • CMS platforms must be able to fetch media externally.
  • Private or expiring URLs are the most common cause of missing images.

They are usually related to:

  • expired credentials
  • missing API permissions
  • CMS security restrictions
  • inaccessible media assets
  • encoding mismatches
  • or external CMS validation rules.

In many cases, the publishing system is functioning correctly — the external CMS environment is preventing synchronization from completing successfully.

👉 Stable CMS publishing workflows depend heavily on:

  • valid API credentials
  • publicly accessible media
  • correct permission scopes
  • UTF-8-compatible environments
  • active content models
  • and reliable synchronization between Search Atlas and the connected CMS platform.