Reference

Troubleshooting

Every message the app can show you, and what to do about it
View as Markdown
RouteAll screens
Find itReference
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

MessageMeaningWhat to do
Enter both an email and a password.One field was left blankFill both
Sign-in failed / Sign-up failedCredentials rejected by the auth providerCheck 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 invitedAn existing admin must invite you. You cannot resolve this yourself
App already exists — “This account supports one app.”The account already owns its one appOpen it from the list; use a separate account for a second app

Sending messages

MessageMeaningWhat to do
No phone number associatedYour app has no number to send fromRequest a number or pair a Mac
Invalid phone numberNot E.164Use +15550109988 form — leading +, country code, no spaces
Cannot create conversationThe recipient cannot receive iMessagesNothing to fix; that number is unreachable over iMessage
Sending number is offlineThe Mac agent behind your number is disconnectedCheck the device in Analytics → Agents; retry once it reconnects
Message blocked — “more than 5 consecutive messages… without a reply”Spam guardSend anyway overrides it, but consider whether you should
Attachments are still uploading…Send pressed too earlyWait for the thumbnails to finish
Message not sent / Failed to send messageGeneric send failureRetry; if it persists check device connectivity

Group chats

MessageMeaning
Not enough participantsAdd at least 2 other numbers — 3 including your agent
Too many participantsMaximum 31 others — 32 including your agent
Intro message requiredThe 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
No new group to createGroup creation is unavailable in this environment

AI agent

MessageMeaningWhat to do
AI Studio couldn’t loadThe studio could not fetch its configurationRetry; 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 gatewayMessaging can still work while this is broken; check the backend, not the gateway
Save failedConfiguration was not writtenRetry — nothing was partially saved
Test failedThe test bench could not get a replyConfirm 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 benchAttach an image instead
Integrations aren’t configured yetNo unified.to credentials in this environmentBackend configuration; not fixable from the UI
No knowledge yetNothing indexedAdd a file, URL or notes — the agent has only its prompt until you do
No activity yet.Nothing has happenedExpected 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, since auto-blocking is silent by design.

Webhooks

MessageMeaningWhat to do
Invalid URLThe webhook URL is malformedInclude the scheme — https://…
Webhooks saved, but secret generation failedURLs saved; signing secret not createdSave again to generate the secret
Exhausted automatic retries (dead-lettered)MessageBlue stopped retryingFix your endpoint, then retry manually
Signature never matchesAlmost always re-serialized JSONSign the raw bytes. See verifying the signature
Only failed or dead_lettered can be retriedThe row already succeededNothing 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 seeWhy
Voice call shows “Please reach out to the team to enable this feature for you.”Calling is not self-service. See the conversation header
Video call does nothingDisabled outright, labelled coming soon
Delete App is greyed out in the account menuPermanently 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
There is no billing screenBilling is handled with the team directly in this release

Devices

MessageMeaning
Device access revoked — “The Mac agent will re-enroll on reconnect.”Success. The device re-enrols on its next connection
Could not revoke device accessThe 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 instead.

Still stuck?

Check the API directly

If the UI and the API disagree, the API is the source of truth.

Contact support

Include the event ID from Failed webhooks or the timestamp from Activity — both make diagnosis much faster.