Troubleshooting
Diagnose the failing layer before changing credentials or reconnecting stores.
Connection and domain errors
Check the hostname first. Marketing and documentation origins do not serve the backend API. For a custom-domain failure, an operator should compare the service's direct URL and deployed release against the custom domain. Do not disable TLS verification or put a production secret into a diagnostic URL.
API and MCP errors
| Result | Check |
|---|---|
401 | Credential type, header, revocation and expiration |
403 | Scopes, ownership, environment and account readiness |
404 | Origin, route, deployment version and proxy mapping |
429 | Retry-After and rate/quota headers |
Tool result isError | Tool refusal reason, schema, authority or approval |
| Empty catalog/wallets | Correct account and environment, visibility rules and sync |
An unauthenticated MCP 401 with an OAuth discovery challenge is expected. A plain browser GET is not a complete MCP test.
WooCommerce
For /.well-known/ucp 404s, check active plugins, permalink rewrites and caching/security rules. For stale products, check scheduled actions, full-sync status, stock visibility and category exclusions. Do not uninstall a legacy plugin before a supported upgrade.
Shopify
For callback loops, inspect app URL, allowed callback URLs and persistent Shopify sessions. For proxy failures, check installation and the shop's configured App Proxy path. For stale catalog data, check full sync and product/inventory webhook delivery.
The app server's /healthz is separate from /apps/aa on a shop. A healthy direct service URL and Google 404 on the custom domain indicate a routing issue. A 404 on both also requires checking the image's route manifest and source commit.
Payment readiness
A connected store or visible product is not proof of payment readiness. Review Stripe Connect status and the specific account/environment in use. A checkout payload or session alone is not a paid order. Never retry a financial operation with a new idempotency key simply because its response was unclear.
Useful diagnostics
Collect the failing URL path, timestamp, source release, selected environment, store identifier and error/status code. Remove authorization headers, keys, cookies and customer/payment data. Keep encryption and signing identities intact while diagnosing the issue.