> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.messageblue.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.messageblue.ai/_mcp/server. # Troubleshooting Route `All screens` Find it Reference Who can open it — A lookup table for the notices the web app shows. Find the wording you saw, and the row tells you whether it is something you can fix. ## Signing in | Message | Meaning | What to do | | --------------------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------- | | *Enter both an email and a password.* | One field was left blank | Fill both | | *Sign-in failed* / *Sign-up failed* | Credentials rejected by the auth provider | Check the address and password; the detail line names the specific cause | | *Access Denied* — *"not authorized to access this application"* | Authenticated, but the account was never invited | An existing admin must [invite you](/settings#team). You cannot resolve this yourself | | *App already exists* — *"This account supports one app."* | The account already owns its one app | Open it from the list; use a separate account for a second app | ## Sending messages | Message | Meaning | What to do | | ------------------------------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------- | | *No phone number associated* | Your app has no number to send **from** | [Request a number](/dashboard#phone-numbers) or pair a Mac | | *Invalid phone number* | Not E.164 | Use `+15550109988` form — leading `+`, country code, no spaces | | *Cannot create conversation* | The **recipient** cannot receive iMessages | Nothing to fix; that number is unreachable over iMessage | | *Sending number is offline* | The Mac agent behind your number is disconnected | Check the device in [Analytics → Agents](/analytics#agents-and-devices); retry once it reconnects | | *Message blocked* — *"more than 5 consecutive messages… without a reply"* | Spam guard | **Send anyway** overrides it, but consider whether you should | | *Attachments are still uploading...* | Send pressed too early | Wait for the thumbnails to finish | | *Message not sent* / *Failed to send message* | Generic send failure | Retry; if it persists check device connectivity | ## Group chats | Message | Meaning | | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | *Not enough participants* | Add at least 2 other numbers — 3 including your agent | | *Too many participants* | Maximum 31 others — 32 including your agent | | *Intro message required* | The opening message is mandatory; it is what creates the thread | | *Cannot create group* — *"Not all participants are iMessage-capable"* | Remove the non-iMessage numbers and retry | | *Invalid group ID* — *"Wait for someone to reply…"* | Expected. See [the waiting period](/group-chats#the-waiting-period-after-creation) | | *No new group to create* | Group creation is unavailable in this environment | ## AI agent | Message | Meaning | What to do | | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | *AI Studio couldn't load* | The studio could not fetch its configuration | **Retry**; if it persists the backend is unreachable | | *Couldn't reach the backend…* | The control-plane backend that serves AI Studio is down — it is a separate service from the messaging gateway | Messaging can still work while this is broken; check the backend, not the gateway | | *Save failed* | Configuration was not written | Retry — nothing was partially saved | | *Test failed* | The test bench could not get a reply | Confirm a configuration is **saved**; the bench runs the saved prompt | | *Unsupported file* — *"Voice notes are not supported at the moment."* | Audio attached to the test bench | Attach an image instead | | *Integrations aren't configured yet* | No unified.to credentials in this environment | Backend configuration; not fixable from the UI | | *No knowledge yet* | Nothing indexed | Add a file, URL or notes — the agent has only its prompt until you do | | *No activity yet.* | Nothing has happened | Expected on a new app. If the agent is deployed and this stays empty, no messages are arriving | Agent replies stopping for **one specific contact** is usually not an error at all — that contact is blocked. Check [Analytics → Blocked contacts](/analytics#blocked-contacts), since auto-blocking is silent by design. ## Webhooks | Message | Meaning | What to do | | ---------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------- | | *Invalid URL* | The webhook URL is malformed | Include the scheme — `https://…` | | *Webhooks saved, but secret generation failed* | URLs saved; signing secret not created | Save again to generate the secret | | *Exhausted automatic retries (dead-lettered)* | MessageBlue stopped retrying | Fix your endpoint, then [retry manually](/failed-webhooks#retrying) | | Signature never matches | Almost always re-serialized JSON | Sign the **raw bytes**. See [verifying the signature](/settings#verifying-the-signature) | | *Only failed or dead\_lettered can be retried* | The row already succeeded | Nothing to do | ## Things that are not errors Several controls look broken but are simply not enabled in this release. None of these indicate a fault: | What you see | Why | | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | **Voice call** shows *"Please reach out to the team to enable this feature for you."* | Calling is not self-service. See [the conversation header](/messages#the-conversation-header) | | **Video call** does nothing | Disabled outright, labelled *coming soon* | | **Delete App** is greyed out in the account menu | Permanently disabled — ask the team to remove an app | | **New conversation** on group chats says *"New group chats can't be started from here right now."* | Group creation is switched off in that environment. See [group chats](/group-chats#when-the-new-group-button-does-nothing) | | There is no billing screen | Billing is handled with the team directly in this release | ## Devices | Message | Meaning | | ------------------------------------------------------------------------ | ---------------------------------------------------- | | *Device access revoked* — *"The Mac agent will re-enroll on reconnect."* | Success. The device re-enrols on its next connection | | *Could not revoke device access* | The revocation did not apply; retry | Revoking is not a routine fix. It can make every number mapped to that device unavailable until it re-enrols. To move a single contact between numbers, [remap the agent](/messages#remapping-the-agent) instead. ## Still stuck? #### [Check the API directly](/api-reference) If the UI and the API disagree, the API is the source of truth. #### [Contact support](/support) Include the event ID from [Failed webhooks](/failed-webhooks) or the timestamp from [Activity](/ai-agent-studio#activity) — both make diagnosis much faster.