Skip to main content

Troubleshooting

The chat widget does not appear on the storefront​

Work through these in order - the first three are the common causes.

  1. The widget is disabled for the workspace. In the eChat backend, check Settings > Widget > Enable widget. See Settings.
  2. The store has no active Mirasvit license. Since version 1.2.0 the storefront widget requires one, and with no active license no widget is served at all. Development domains are unaffected, as elsewhere in Mirasvit extensions.
  3. The page is excluded. Do not load the widget on pages matches either a URL fragment or a Magento full action name. On a matching page nothing is injected. See General Settings.
  4. The knowledge base is still empty and Hide the chat until the knowledge base has content is on. Run the sync - see How to sync data manually.
  5. The module is disabled or static content is stale. Re-run bin/magento setup:upgrade, cache:clean, and the static content deploy from the installation steps.
  6. A Content Security Policy is blocking it. The extension ships a csp_whitelist.xml covering echat.mirasvit.com for scripts, styles, connections (including wss://), images, and media. If you maintain your own restrictive CSP outside Magento's CSP module - at the CDN or web server, for example - that host has to be allowed there too.

The chat replies with an error, or stops replying​

This is almost always the AI provider, not the extension. Open Settings > AI Providers in the eChat backend and read the status on each credential; Revalidate re-checks on demand.

StatusMeaning and fix
INSUFFICIENT_QUOTAThe key is valid but the provider account is out of credit. Top up the account. This is the most frequent cause of a chat that worked yesterday and does not today.
INVALID_KEYThe provider rejected the key - revoked, mistyped, or from a different project. Issue a new key and replace it.
EMPTY_KEYNo key is stored on this credential. Edit it and enter the key.
RATE_LIMITEDThe provider is throttling the key, usually because the account's usage tier is too low for your traffic. Raise the tier with the provider, or add a second provider lower in the chain.
MODEL_UNAVAILABLEThe selected model is not available to this key. Some models require a specific plan or account verification. Select the recommended model, or unlock the model with the provider.
TRANSIENT_ERRORA temporary provider failure. Revalidate; the fallback chain has already routed traffic onwards.
UNCHECKEDNever probed. Click Revalidate.

Two things make this self-correcting:

  • A fallback chain with a second provider from a different vendor keeps the chat alive through a single vendor's outage.
  • Email me when the AI chat stops working, on the AI Assistant tab, tells you when every provider is down. At most one email a day, up to three per outage.

A provider quota error in detail​

An error such as 429 Too Many Requests - "You exceeded your current quota, please check your plan and billing details." means the provider account behind the key has no credit or has hit its rate limit. Note that AI usage is billed to your own provider account, not to Mirasvit - see Costs and billing.

With OpenAI specifically, API usage is billed separately from a ChatGPT subscription: a ChatGPT Plus account does not fund API calls. On platform.openai.com, add billing details, purchase API credits, and optionally enable auto-recharge. New accounts start on the lowest usage tier with strict rate limits, and the tier rises with spend; Limits in the left sidebar shows the current tier and what the next one needs. The other providers work the same way, each with its own console.

"Configure Chat" does not open the backend​

The button verifies the connection first, so it reports rather than opens:

  • A retry message means eChat could not be reached. Your credentials are left untouched; try again.
  • A prompt to register again means the workspace no longer exists on the eChat side. The stale credentials are cleared and you can connect a new workspace.

Each Configure Chat button - the global one and each store-level override - checks its own scope, so on a multi-store setup make sure you are clicking the one for the scope you mean.

The chatbot answers about the wrong store, or shows the wrong workspace​

At website or store-view scope, the account panel reads and acts on the credentials of the scope you are editing. Switch the configuration scope to the store view in question and check its Instance ID there. The backend's Workspaces tab lists every workspace in the account with its domain and Magento admin URL, which is the quickest way to see which workspace belongs to which store.

A document I edited in the backend reverted​

Synced documents are keyed by identifier, and the sync overwrites whatever is stored under its own identifiers - by 2:00 AM at the latest. Edit the source in Magento, or use an identifier of your own for hand-written content. See Knowledge Base.

A customer cannot submit a ticket or look up an order​

Both actions require a verified email address. The usual causes:

  • "Verification code has expired" - codes last 10 minutes. The customer should request a new one.
  • The code was already used - a code works once.
  • Too many requests - new codes are limited to 100 per hour per IP address.
  • Ticket actions are missing entirely - the ticket capabilities exist only when Mirasvit Help Desk MX is installed.

See What the chatbot can do for the full verification rules.

The sync fails or skips content​

  • One failing content source is logged and skipped; the rest of the run continues. Check var/log/ for what was skipped.
  • A source with nothing to send creates no category, so a missing "Knowledge Base" category on a store without Mirasvit Knowledge Base installed is expected.
  • Use --dry-run to see exactly what a source would send without contacting eChat, even on a store whose credentials are not set up: bin/magento mirasvit:echat:sync --dry-run --limit=5.