Seekmodo developer docs

← Back to Connectors

Troubleshooting · WordPress & WooCommerce connector

Both verticals ship in the same plugin (seekmodo-wordpress), so the same troubleshooting playbook applies whether you're running the content vertical, the commerce vertical, or both on the same site.

"Connect to Seekmodo" fails

Symptoms: the admin button bounces back with Pairing failed or the seekmodo.com browser tab hangs.

1. Is wp_remote_post() allowed outbound? Some hosts firewall outbound HTTPS to non-allowlisted hosts. Allowlist mcp.seekmodo.com and seekmodo.com.
2. Is the WP site's clock skewed more than 5 minutes from real time? HMAC signing uses time(); greater than 5 minutes drift produces Invalid timestamp errors. Run wp cli info and check the system time.
3. Try the CLI flow: wp seekmodo connect --tenant=… --secret=… — bypasses the browser round-trip and surfaces verbose errors.

Wordfence-running sites

A few merchants hit a "Connect lands on wp-admin" symptom because Wordfence's WAF intercepts the return GET. If pairing still fails after upgrading to v0.3.1+:

1. Wordfence → Firewall → Allowlisted URLs → add wp-admin/admin-post.php?action=seekmodo_wp_connect_callback
2. Wordfence → Firewall → Brute Force Protection → confirm "Lock out users after how many forgotten password attempts" isn't catching the connect bounce.

Search returns nothing

In MODE=active or enforce with the gateway down, the connector falls through to native WP search. If you're seeing literally zero results:

1. wp seekmodo health — shows current mode, breaker state, gateway last-reach timestamp.
2. Check wp-content/uploads/seekmodo-shadow.log for circuit-breaker open events.
3. Force native by setting wp option update seekmodo_wp_mode off and try again — confirms WP's native search still works.

Index never updates

wp seekmodo index --status     # cursor + last-tick timestamps
wp cli event list | grep seekmodo
wp seekmodo index --delta -v   # verbose, prints per-doc actions
wp seekmodo index --full       # force a full reindex

If wp cli event list shows seekmodo_wp_index_tick in the past with no recent runs, your wp-cron is stalled — set up a system cron driver instead of relying on request-driven wp-cron.

Storefront host is wrong (e.g. staging clone returns null)

This is the expected behavior of the domain lock — see the connector's Multi-environment installs section. To resolve:

# Confirm the canonical host on admin.seekmodo.com:
wp option get seekmodo_wp_storefront_host

# If wrong, fix on admin.seekmodo.com (Tenant -> Storefront domain) and
# force a snapshot pull instead of waiting 5min:
wp seekmodo refresh-config

If you're moving from a dev / staging mirror to a fresh production hostname, use the connector's self-service promote flow instead of editing the option by hand: Settings → Seekmodo Search → Promote dev to production.

Breaker stuck open

The breaker opens for 60s after 5 consecutive 5xx within 30s. If you've fixed a gateway-side issue and want to clear it immediately:

wp option delete seekmodo_wp_breaker_state

The next request reinitializes a closed breaker.

Typeahead first row is invisible / white-on-white

Symptom: the dropdown renders rows correctly except the very first one, which only becomes visible when the user hovers or arrow-keys onto it.

Cause: the theme's style.css (or a similar global sheet) has a bare a:visited { color: #fff } rule — a holdover from styling nav links on a dark hero. That selector is (0,1,1) specificity. Your typeahead row anchor selector is also (0,1,1), so source order decides — and the theme's main style.css almost always loads later, so it wins. The bug only hits the first row because that's the most-clicked / most-likely-:visited URL.

Fix: bump the row anchor selector to (0,2,1) by chaining the link pseudo-classes:

.my-typeahead__result a,
.my-typeahead__result a:link,
.my-typeahead__result a:visited {
    color: var(--your-row-text-color);
}

"Class not found" after upgrade

The opcache has a stale path. Clear opcache:

wp eval 'opcache_reset();'
# or restart PHP-FPM
sudo systemctl reload php-fpm

Useful one-liners

# Last 10 shadow-mode divergences:
wp seekmodo shadow-report --tail=10

# Aggregated shadow-mode signal over the last 24h (jaccard, top-N match):
wp seekmodo shadow-report --window=24h

# Pretty-print current options:
wp option list --search='seekmodo_wp_*' --format=table

# Force a fresh tenant.snapshot pull:
wp seekmodo refresh-config

# Gate before flipping to active:
wp seekmodo cutover-readiness --window=7d

WooCommerce-specific gotchas

• Products don't show up in the typeahead, only blog posts do. Run wp seekmodo index --full to seed products, variations, brands, and stock state into the gateway. The commerce vertical's indexer is delta- driven on woocommerce_update_product and friends, so a freshly-paired site needs the initial full reindex before the dropdown can render product cards.
• Variation prices are wrong / missing. v0.3.0 realigned the commerce schema to gateway-canonical field names (name, url, in_stock, sale_price, currency). On existing tenants, run the add-woocommerce-commerce-fields.php migration on the gateway side before the v0.3.0 connector points at them, then bump the schema version with wp seekmodo index --full to repopulate.
• On-sale / out-of-stock badges aren't rendering. The connector's typeahead config exposes i18n.on_sale and i18n.out_of_stock strings; some heavily- customised themes filter seekmodo_typeahead_config and accidentally drop the i18n keys. Re-attach them via the same filter or remove the customisation.

When to escalate

Email [email protected] with:

• wp seekmodo diagnose output — one-shot bundle of options, cron state, breaker state, last 50 shadow-log lines.
• Your tenant ID.
• The exact MODE= value and the timestamp of when the issue started.

Security issues: [email protected] — see also our security disclosure policy.

Want a hands-on walkthrough? Contact support — we'll diagnose the diagnose output with you over chat.