OCMLABS/MODULE-WORDPRESS · TROUBLESHOOTING

Troubleshoot common WordPress Integration issues

  • Magento
  • Adobe Commerce
  • Hyvä

Blog Shows 404

Check 1: Is the module enabled?

TERMINAL
$ bin/magento module:status | grep OCMLabs
# Expected: OCMLabs_WordPressIntegration - Module is enabled

If disabled, run:

TERMINAL
$ bin/magento module:enable OCMLabs_WordPressIntegration
$ bin/magento setup:upgrade
$ bin/magento cache:flush

Check 2: Is the module configured?

Go to Stores > Configuration > OCMLabs > WordPress Integration and verify:

  • WordPress URL is set and reachable
  • API Key is set

Check 3: Flush the cache

TERMINAL
$ bin/magento cache:flush
NOTE /

The router reads the configured base URL from config, which is cached. A stale cache can cause routing to fail.

Upgrade from 1.x Fails with “Duplicate entry”

On 2.0.0 to 2.0.5, bin/magento setup:upgrade from the 1.x module (OrangeCollar_WordPressIntegration) can stop with Unable to apply data patch ... RenameConfigPathsPatch and a Duplicate entry error for setup_module or core_config_data. Saved settings then stay under the old orangecollar_wordpress/ names and the blog returns a 404. Update to 2.1.0 or later and run setup:upgrade again.

  • Check that Enable WordPress Menus is Yes and a Sidebar Menu is selected, at the store view you are viewing.
  • If the Sidebar Menu list only shows “None”, Magento could not reach WordPress. Save the connection settings and use Test Connection.
  • Check that the page layout for that page is not 1 column, and that the page has a sidebar (author pages do not).
  • If menu links still point at WordPress, the WordPress URL in the Connection settings does not match the address WordPress uses for itself. See Where Menu Links Point.

Blog Home Does Not Show the WordPress Front Page

  • Check that Blog Home Page Content is a Front Page option, at the store view you are viewing.
  • In WordPress, check Settings > Reading is set to A static page with a published Homepage. If it shows latest posts, the blog home falls back to the post list.
  • After choosing a different front page in WordPress, flush the Magento cache.

WordPress API Returns 403 Forbidden

The Content Bridge plugin returns 403 with Invalid API key. when the API key does not match (and 503 when no API key is set in WordPress). Verify:

  1. The key in Magento admin (Stores > Configuration > OCMLabs > WordPress Integration > Connection > API Key) matches the key shown in WordPress Admin > Settings > OCMLabs Content Bridge for Magento
  2. The OCMLabs Content Bridge for Magento plugin is active in WordPress
  3. The API key was not regenerated in WordPress after being saved in Magento

WordPress API Is Unreachable from Magento Server

The “Test Connection” button in Magento admin shows an error, or the blog shows blank content.

  • Verify the WordPress URL in Magento config is the server-accessible URL, not a local dev URL
  • Check firewall rules between the Magento server and the WordPress server
  • Check that the WordPress server is not blocking requests from the Magento server’s IP
  • Increase the connection timeout if the WordPress server is slow to respond

Blog Content Shows Blank or Partial

Content processor issue

Check that ContentProcessor is not stripping valid content. Enable Magento debug logging and check var/log/ocmlabs_wordpress.log.

Cache issue

Flush the cache and reload. If the content appears after a flush but disappears again, there may be a cache tag issue.

WordPress Edits Do Not Show on the Storefront

On 2.0.3 and later, the cache purge webhook clears both the module’s data cache and the full page cache (built-in or Varnish), so an edit shows on the next page load. On 2.0.2 and earlier, the webhook cleared only the data cache, and cached blog pages kept the old content until the full page cache expired. Update to the latest version.

If edits still do not show:

  • Check that the webhook reached Magento: each successful purge logs WordPress webhook: Cache purged in var/log/system.log
  • With Varnish, check that Magento is configured to send purge requests to it (Stores > Configuration > Advanced > System > Full Page Cache, and the http_cache_hosts setting in app/etc/env.php)
  • A CDN in front of Magento that caches HTML has its own cache, which the webhook does not purge

Store Top Menu Missing on Blog Pages

On 2.0.4 and earlier with Varnish, the blog home, post, category, tag and author pages render without the store’s top navigation menu, on Luma and Hyva. Blog search results and other store pages still show it. Update to 2.0.5 or later, then flush the cache and purge Varnish.

If the menu is still missing on a second store view, check how you switched to it. In a browser with no store cookie, a URL with ?___store=code shows no top menu on any cached page, store pages included. That is how Magento’s ESI includes work with Varnish: the menu request does not carry the ___store parameter. Switch store views with the store switcher instead.

Blog Pages Show the Wrong Store View

On 2.0.4 and earlier with Varnish, opening a blog page on a non-default store view clears Magento’s X-Magento-Vary cookie. The visitor’s next cached pages can then come from the default store view, with its theme and content. Update to 2.0.5 or later.

Webhook Purge Fails (403 Forbidden)

Magento returns 403 when Enable Webhook Cache Purge is set to No. Set it to Yes in Stores > Configuration > OCMLabs > WordPress Integration > Cache.

Also check that the Magento webhook endpoint is not blocked by a WAF or CDN rule.

Webhook Purge Fails (401 Unauthorized)

Magento returns 401 when the webhook signature does not match.

  • If a Webhook Secret is set in either Magento or WordPress, set the same value on both sides
  • If no Webhook Secret is used, verify the API key in WordPress settings matches the API key in Magento configuration
  • Verify the webhook URL in WordPress settings matches your Magento store URL exactly (including HTTPS)

Permission Errors in Docker

TERMINAL
$ docker compose exec -T php chown -R www-data:www-data /var/www/html/var /var/www/html/generated

Port Conflicts in Docker

Change MAGENTO_PORT or WORDPRESS_PORT in magento2-wordpress-docker/.env.

Checking Logs

  • Magento system log: var/log/system.log
  • WordPress integration log: var/log/ocmlabs_wordpress.log
  • PHP error log: depends on your server configuration

See also

In this module