Troubleshooting

Troubleshooting

Test Connection fails with 401 Unauthorized

Your API key is wrong or has been rotated. Generate a fresh key from your provider's console (OpenAI: platform.openai.com/api-keys, Anthropic: console.anthropic.com/settings/keys), paste into Models, and re-test. Keys are stored encrypted via OAssist_Crypto - if the WordPress AUTH_KEY salt was rotated since you saved the key, OAssist can't decrypt it and you'll see a stale-key error. Re-save the key to fix.

Embeddings fail during indexing

The embedding provider is separate from the chat provider. By default it's set to OpenAI Embeddings (text-embedding-3-small). If you've configured a chat provider but not embeddings, indexing fails. Configure the OpenAI Embeddings row under Models with a valid OpenAI key, or switch the embedding provider under Settings -> Embeddings.

Chat widget doesn't appear on the storefront

1. Channels -> Site: confirm Enabled is on.
2. Check the Allowed pages patterns - by default it's site-wide, but a restrictive pattern can hide it.
3. View source on the storefront and search for oassist-widget. If absent, another plugin or theme may be stripping wp_footer output. Inline embed via shortcode bypasses this.
4. JavaScript console may show errors - if OAssist_Channel_Site couldn't fetch its config, the widget skips render.

Tool calls fail with permission denied

The tool's scope is authenticated and the visitor is not logged in. For get_order_status and track_shipment, OAssist accepts guest verification (order number + email match) - the assistant should ask for both. If you want logged-in only, leave the scope as-is. To make a tool accessible anonymously, edit the row in oas_tools and set scope = 'anonymous' (only do this for tools that don't expose private data).

Costs are higher than expected

A few common causes:

• Long system prompts push every request over the cache threshold. Trim Persona instructions where possible.
• No prompt cache hits: check the cache hit rate on Analytics. If it's near 0, identical questions aren't cached - likely because your persona varies per-request (e.g., includes the current time). Move volatile data out of the system prompt.
• Wrong model picked: gpt-4o is ~10x more expensive than gpt-4o-mini. For most shopping-assistant tasks, the smaller model is sufficient. Switch under Models.
• Runaway tool loops: if a tool returns malformed data, the LLM may retry repeatedly. Check Inbox for conversations with high turn counts and review the tool call sequence.

Conversations disappear from the inbox

oassist_cron_cleanup runs daily and prunes conversations older than the retention window (default 90 days). To keep history longer, raise the retention under Settings -> Data Retention, or export to CSV via Inbox -> Export before the cleanup runs.