Troubleshooting

Symptoms, causes and fixes for the problems people hit while integrating.

The chat opens but never connects

• Wrong key for the build. A kl_pub_dev_… key only works while the agent is published to development. Publish, or use the production key.
• No published version. Session bootstrap fails with agent_not_published. Publish the draft to the environment the key belongs to.
• Corporate proxy blocks WebSockets. The SDK falls back to SSE automatically with KletsoAutoTransport. If you forced WebSocket, switch to auto.
• Web: mixed content. A page served over http:// cannot open wss://. Serve your app over HTTPS or use http://localhost.

Messages send but nothing comes back

• Check the conversation in the dashboard: if you see tool.failed with a 4xx or 5xx from your API, the tool URL or auth is wrong. Use Tools → Test.
• message.completed with finishReason: "error" and a provider error usually means the model key is invalid or the model id is not available on your plan. Anthropic rejects temperature on Claude 5 models; the runtime omits it for those automatically.
• Rate limited: 429 rate_limited after 30 messages a minute per user.

The model asks questions instead of calling tools

Real models are cautious when the prompt is vague. Say explicitly which tool to call for which intent and what defaults to use (“products → search_products with the user’s words as query”). Tighten tool descriptions the same way. Preview in the builder until the first turn calls the tool.

Surfaces render as plain text

• The component type is not on the agent’s UI allowlist. Add it and publish.
• The type is custom and not registered in the app (registerComponent). Check for typos in the type name (acme.productCard).
• The manifest was not synced, so the model does not know the props. Run dart run kletso_flutter:sync and import.

Local actions do nothing

• No handler registered under that name, or a name mismatch between the surface (addToCart) and registerAction.
• The handler needs a BuildContext and none was available: set client.ui.contextProvider = () => navigatorKey.currentContext.
• Server-initiated commands are off by default: set allowServerCommands: true in KletsoConfig.

Notifications do not appear

• KletsoNotificationHost is missing from the widget tree. Wrap your app (or the screens that should show banners) with it.
• The rule is in the other environment. Rules are per environment.
• The user has no open socket and no push token. Register the token with registerPushToken and configure FCM under Triggers → Push delivery.
• A banner auto-dismisses after 8 seconds by default; a toast after 4.

Push arrives but renders twice

Pass the payload to handlePushPayload exactly once per delivery. The SDK dedupes on notificationId when the same notification also arrived over the socket.

Web build: Flutter looks frozen while I automate it

Chrome throttles background tabs. Bring the tab to the foreground when driving the app with a browser automation tool.

Still stuck

Email hello@kletso.ai with the conversation id (shown in the dashboard) and the request id from the error body. Both are safe to share.