# Troubleshooting

Start with the result you expected, not just the last button you clicked. A draft, accepted connection, launched Iris and delivered reply are separate outcomes.

## Iris is not answering

1. Confirm the selected business.
2. Check **Home** for approval. A business under review cannot launch yet.
3. Review **About business** and **Save changes**. An unsaved onboarding draft is not a completed setup.
4. Check launch status. If launch is starting or unconfirmed, recheck before deciding to retry.
5. Check **Connections** for the channel you are testing, or **API keys** for a website. Another channel’s connection does not cover this one.
6. Check **Billing** for the balance and follow the displayed status.
7. Try one simple question with fictional information. If customer preview works but the real channel does not, investigate that channel or your website backend.

**Launched** is not a continuous online monitor. **Connected** means setup was accepted, not guaranteed future delivery. Avoid repeatedly resending messages while the outcome is uncertain.

## I see “Open on desktop”

The management dashboard currently requires a desktop or laptop-sized browser. Open the same link on a computer. The public docs and secure one-time key-entry page work on phones; this does not mean the whole dashboard is mobile-enabled.

## A Meta channel will not connect

Use the intended account and check your permissions for the selected business asset. Finish the complete provider sign-in flow and return to inspect the result. Closing a popup or an interrupted save is not confirmation.

For WhatsApp, follow the [number onboarding checklist](https://docs.flowlith.com/whatsapp), especially for an existing WhatsApp number. Do not delete an account, reset verification or move a number just to experiment. Follow the supported provider flow and ask for help if it cannot complete.

If the dashboard requires disconnecting before replacing an account, review the selected account carefully: disconnecting affects that channel’s ability to receive new messages. Test again after reconnecting.

## I saved something, but Iris uses the old version

| Change | What to check |
| --- | --- |
| About business or Memory | Wait for confirmed saving; pending is not in use yet. |
| Asset or skill | Review all pending changes and **Apply to Iris**; Save leaves a draft. |
| External Action | Review the exact version, Test, then explicitly turn it on. |
| Connection or credential | Linked Actions may need review, a new Test and activation. |
| AI-app client package | Refresh or update the imported copy in that app if needed. |

For conflicts, copy your edits, reload, and merge with the current version. Do not repeatedly overwrite an old version. If Apply is unconfirmed, inspect its status before retrying. Applying teaching does not send a test message.

## Website chat disconnects or repeats a message

Read the [API reference](https://docs.flowlith.com/website) and [embed example](https://docs.flowlith.com/website-embed). This is a server-to-server stream, not a browser request with an exposed business key.

Keep the same customer identity for a continuing chat. Generate a message ID once for a new message, and preserve the same message ID and body when reconnecting it. Do not create a new ID to force an uncertain retry. Respect retry guidance; do not retry terminal errors automatically.

For CORS errors, check that the browser calls your backend, not Flowlith directly. For a rejected key, check server-side configuration and whether it was rotated or revoked. Never print a key into a console, ticket or screenshot.

## A tool Test failed or the result is unknown

Check the [Actions guide](https://docs.flowlith.com/actions) for the integration mode and request/response shape. Verify credentials in the secure form and permissions at the destination. Do not paste credentials into a prompt to help debug.

A Test can perform a real write. A timeout does not prove nothing happened. Inspect the destination before repeating a booking, order, payment-related change or lead creation. A successful read test does not prove a write is configured; a passing old version does not activate a changed version.

If a tool or connection changed, review and test the current setup using safe data. Never enable an Action whose Preview you do not understand.

## The AI app sees tools but not my business

Tool discovery and account authorization are different. Complete browser sign-in, return to the AI app and ask it to list businesses read-only. Check the email address and selected business. An empty list can be correct for a new account.

After account-wide sign-out, an email change or revoked authorization, reconnect through the browser. If your app or workspace disables custom MCP connections, use the dashboard or ask its administrator; do not paste a token into chat to bypass the restriction.

## A document or voice note was not understood

Check [supported channels and media](https://docs.flowlith.com/channels). A successful upload or visible attachment does not guarantee accurate reading. Try a smaller supported file, a clearer recording or the relevant text. If Iris requests a typed or resent message, follow that instruction rather than repeatedly sending the unreadable file.

Remove credentials and unnecessary personal information from troubleshooting samples. Compare important answers with the original document before relying on them.

## Credits or payment look wrong

Check **Billing** for the balance and payment history. An answered customer preview uses credits too. A payment screen closing is not itself proof that credits updated; reload and check the confirmed status before paying again.

If the provider shows a charge but Flowlith has not updated, report the payment reference through support. Never send card details, a UPI PIN, an OTP or an access token.

## Report a useful, safe issue

Use **Report an issue** on Home or in Settings. Flowlith replies to your signed-in email. Include the expected result, observed result, time and smallest reproduction. Redact credentials, private customer information and confidential URLs.

```text
Subject: [Short description]
Business: [Your business name]
Area: [WhatsApp / website / Actions / account / billing]
Time and timezone: [When it occurred]

Steps:
1. [First action]
2. [Next action]

Expected: [The result you wanted]
Observed: [Visible result or non-secret error wording]
Status checked: [Approval / connection / launch / applied version]
Safe test used: [Fictional data or test system]

I removed keys, login codes, customer details and private links.
```

If a secret was exposed, rotate it at the service that issued it and update the secure connection before continuing. Removing it from a message alone does not revoke it.

[Start here](https://docs.flowlith.com/) · [How Iris works](https://docs.flowlith.com/how-iris-works) · [External APIs and Actions](https://docs.flowlith.com/actions)