Troubleshooting
The bubble doesn't show, a key or site is refused, uploads fail, or no one answers.
The SDKs print setup mistakes to the browser console or the app's log, starting with
[Mawgood chat]. The error event gives the same serverCode (Events).
The bubble doesn't show
- Is the card on? In your Mawgood › Overview and channels › Website & app chat. With it
off the chat API answers
409 chat_disabled. - Is your site or app in the key's list? See
origin_not_allowedbelow. A live key with an empty list works nowhere; a test key with an empty list works onlocalhostonly. - Both values set? The script tag needs
data-site-keyanddata-mawgood-id([Mawgood chat] Add data-site-key and data-mawgood-id to the script tag.); the element needssite-keyandmawgood-id. - Is the Mawgood live? An archived Mawgood answers
409 mawgood_unavailable, and a suspended workspace403 workspace_unavailable. - Is the launcher hidden? The look's
launcher.hiddenis meant for your own button (Mawgood.open()). The look'sbehaviour.include/excludepatterns can also keep the bubble off a page. - A Content-Security-Policy? Check the console for blocked requests and add the CSP lines.
- Staging key on production, or the other way round? A key belongs to one environment. Use
data-environment="staging"(web),environment="staging"(React Native) orMawgoodEnvironment.staging(Flutter) with a staging key.
The card says Not installed yet until a bubble has opened a session with one of the Mawgood's keys.
origin_not_allowed (403)
The key doesn't list where the call came from.
- Web: add the exact origin the browser shows in the address bar: scheme and host, and the port
if it isn't the default (
https://shop.example.com, notshop.example.comorhttps://shop.example.com/).www.example.comandexample.comare different origins.https://*.example.comcovers subdomains but notexample.comitself. - On your machine:
localhostand127.0.0.1work only with a test key. - Apps: add the iOS bundle ID and the Android package name exactly (they're case-sensitive).
Debug builds with a suffix (
com.example.app.dev) need their own entry. The Flutter SDK prints which ID to add.
The SDK says which origin or app ID to add in the console and stops (no retries, no offline banner); the launcher stays hidden. With a valid site key the refusal is readable from any origin (its body names only the origin to add); with an unknown or revoked key the browser only shows a CORS error.
invalid_api_key (401)
The site key is missing, mistyped, revoked, or expired (an old key stops 7 days after it was
rotated). Copy it again from the card. A secret key (mwg_sk_…) is never accepted here, and
403 mawgood_mismatch means the key belongs to another Mawgood than the Mawgood ID you passed.
chat_volume_limit and new_chats_limit (409)
chat_volume_limit: the Mawgood reached its new conversations for today (2,000 by default, or lower if you lowered it in the card's Usage limits). Existing chats keep working.new_chats_limit: one device opened 10 new chats today, or one IP 200 for this Mawgood.
The message fails with «try again later»; the SDKs don't retry it by themselves. The Mawgood team is alerted when a Mawgood hits its daily cap.
Uploads fail
- Over 10 MB, or another type? The bubble takes JPEG, PNG, WebP and GIF images, PDFs and voice
notes only (
413 file_too_large,415 unsupported_type). - From a website only, while apps work? The file goes straight from the browser to Mawgood's
storage (Cloudflare R2) with a signed
PUT, which needs the storage's CORS rule for the chat bubble. That rule is on Mawgood's side: ask Mawgood Assistant (the round button at the bottom corner of the dashboard) or write to[email protected]if uploads fail from every site. - Your CSP?
connect-srcneedshttps://*.r2.cloudflarestorage.com. - Attachments or voice notes off? The look's
features.attachmentsandfeatures.voiceNoteshide them; in React Native the pickers and recorder need their adapters.
No replies
- The Mawgood isn't live, or the chat is with your team: while a teammate has the conversation, the Mawgood stays quiet. The bubble shows the away text when no one is online.
- Credits ran out: at zero credits the Mawgood stops replying on every channel and new messages go to your team ("Out of credits"). Top up and new chats go to the Mawgood again.
- The hourly cap: past 1,000 AI replies an hour on this channel (or the lower cap you set), chats go to your team with the reason "Chat hourly reply limit", and the bubble says the team will reply.
- Realtime blocked? Behind proxies that block WebSockets the SDKs switch to Server-Sent Events by themselves. Replies also load when the page or app comes back to the foreground.