# Troubleshooting

## "Connect to Seekmodo" fails

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

Checklist:

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 > 5min from real time? HMAC signing
   uses `time()`; >5min 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.

## Search returns nothing

In `MODE=active` or `enforce` with the gateway down, the connector
SHOULD fall through to native LIKE 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

```bash
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 — see "WP-Cron vs system cron"
in [`PLATFORM_NOTES.md`](PLATFORM_NOTES.md).

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

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

```bash
# 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
```

## 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:

```bash
wp option delete seekmodo_wp_breaker_state
```

The next request reinitializes a closed breaker.

## Typeahead "first result is invisible / white on white"

Symptom: the popover renders rows correctly **except** the very first
one, which only becomes visible when the user hovers/keyboards onto
it. Other rows look fine.

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 (e.g. `.my-typeahead__result a`) 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:

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

Full write-up + hover-state pattern: [`TYPEAHEAD.md`](TYPEAHEAD.md)
("Theming gotcha: `a:visited`").

## "Class not found" after upgrade

Means the opcache has a stale path. Clear opcache:

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

## Useful one-liners

```bash
# 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
```

## When to escalate

Email `support@seekmodo.com` 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: `security@seekmodo.com` (also
<https://seekmodo.com/security>).
