Skip to content
Ankole

FAQ and troubleshooting

For AI Agents: the Markdown version of this page is at https://ankole.agentbull.com/en-US/docs/faq/index.md. The documentation index is at https://ankole.agentbull.com/en-US/llms.txt.

Start here when troubleshooting a symptom rather than reading a full setup walkthrough. Isolate the earliest failing boundary in the table below, then jump to your specific identity or chat provider—for step-by-step installation, see Quick start.

Find the failed boundary

What you observe Check first
/setup or the Console does not open Deployment, control-plane, function-runtime, PostgreSQL, DNS, and HTTPS
The Console or Pod opens, but sign-in fails or the directory is incomplete Enterprise IdP SSO, passwordless Email OTP (SiteCredential via authn.email.mail), principals.pod_login_policy, and siteadmin / pod_admin membership
The Agent works in the Console, but one IM gets no message That Channel Provider and its signal routing rule
The IM message enters Ankole, but the Agent cannot generate a reply LLM Provider, model profiles, and Worker
Only one platform fails Select that Provider below; do not apply another platform’s fix

Problems shared by all platforms

What should I check when /setup or the Console does not open?

Symptom
The page times out, refuses the connection, returns 502, or stays blank before any Provider setup begins.
Meaning
Either the control plane is unhealthy, or DNS, the reverse proxy, or the Ingress is not routing traffic to it—downstream Provider errors are usually knock-on effects.
Fix
  1. Check control-plane, function-runtime, PostgreSQL, and the reverse proxy, and fix the earliest error in the logs.
  2. If connecting directly to the control plane works, inspect DNS, TLS certificates, and the proxy upstream target.
  3. Do not delete the database or persistent volumes—a startup failure does not indicate corrupted data.

Where is the activation code for first-time setup?

Symptom
/setup asks for the activation code, but the startup terminal was closed or the code scrolled past in the logs.
Meaning
The control plane generates this one-time code solely for initial setup and invalidates it as soon as the first siteadmin administrator signs in.
Fix
  1. If setup is still incomplete, pick your deployment method in Quick start and run the log command shown in that tab.
  2. Search the logs for SETUP ACTIVATION CODE rather than guessing from browser storage or database rows.
  3. If the site already has an administrator in siteadmin (or pod_admin for a Pod), sign in directly via passwordless Email OTP (SiteCredential via authn.email.mail) or your configured enterprise IdP SSO instead of running /setup again.

Why is a selected adapter still missing from the Provider list?

Symptom
You enabled and saved the plugin, yet its adapter option does not appear in /setup or on the Identity Provider / Signal Routing pages.
Meaning
During /setup, Ankole exposes all compiled plugins and filters downstream forms by your saved selection; once setup finishes, plugin changes saved in the Console take effect on the next control-plane start.
Fix
  1. If you are still inside /setup, go back to Plugins, save your selection, and reopen Administrator sign-in—no restart is needed.
  2. If setup is already complete, restart only the control plane (leave PostgreSQL and persistent data untouched), confirm that the plugin shows as active, and reopen the Provider page.
  3. If the control plane fails to start after enabling the plugin, fix the first plugin initialization error in its logs.

No chat platform gets a reply. Is this still a channel problem?

Symptom
Channels, direct messages, and even a second chat app all fail to get replies, and chatting directly with the Agent in the Console also fails.
Meaning
When Console chat fails too, the fault lies in the shared downstream path—the LLM Provider, Agent model profiles, or Worker—rather than an individual chat platform’s event permissions.
Fix
  1. Confirm that the LLM Provider is enabled and that its API credential and model names are valid.
  2. Verify that the Agent has a valid primary profile and that its selected profiles resolve correctly. Check Console → Workers for failures on the Agent's Worker.
  3. Complete one end-to-end conversation in the Console first, then return to your chat-platform tab below.

A schedule did not run on time. What should I check first?

Symptom
The schedule exists, but it did not fire at the expected time or displays an unexpected next-run timestamp.
Meaning
Either the schedule is disabled, the schedule timezone or cron expression is misconfigured, or the control plane was not running at the scheduled trigger time.
Fix
  1. Open the schedule, verify that it is enabled, and check the next-run timestamp displayed in the Console.
  2. Verify both the schedule timezone and cron expression, relying on the Console’s computed next-run timestamp rather than mental math.
  3. Click Run now: if the manual run succeeds, fix the schedule timing; if it fails, inspect the run record.

A schedule ran. Why did no result arrive in chat?

Symptom
A run record exists, yet no Agent message arrived in the target chat or conversation.
Meaning
The schedule triggered properly, so the failure occurred downstream—in the target route, Channel Provider, Agent model profiles, or Worker availability.
Fix
  1. Open the run record, check its status, and read the earliest error message.
  2. Verify the target Agent, conversation or chat destination, and its signal routing rule.
  3. Confirm that the Agent's model profiles work and that Console → Workers shows a healthy Worker for that Agent.

Identity Provider troubleshooting

Your Identity Provider (IdP) governs Console sign-in, contact profiles, and org-chart sync. Select your enterprise’s identity source below—Slack Socket Mode, Entra ID Graph webhooks, and Google Workspace scheduled sync rely on distinct transport paths and require different checks.

Slack sign-in fails during the authorization redirect

Symptom
Slack reports a redirect_uri mismatch before returning to Ankole, or redirects to the wrong URL.
Meaning
Either the Redirect URL registered in Slack does not match the callback URL shown in /setup character for character, or Ankole holds a Client ID from a different Slack app.
Fix
  1. Copy the complete callback URL from /setup into OAuth & Permissions → Redirect URLs.
  2. Compare scheme, host, port, path, and Provider ID character by character.
  3. Save the Slack app and start a fresh sign-in from Ankole rather than refreshing the failed authorization tab.

Slack sign-in works, but members or user groups are missing

Symptom
You can sign in to the Console, but Principals or permission groups are empty or missing recent workspace members.
Meaning
Either the Slack app is missing users:read, users:read.email, or usergroups:read/team:read scopes, its Bot User OAuth Token was minted before you added those scopes, or full directory sync has not run yet.
Fix
  1. Add all identity scopes listed in Quick start.
  2. Reinstall the app into the workspace after any scope change and save the refreshed Bot User OAuth Token in the IdP.
  3. Run and verify a full sync before troubleshooting realtime event sync.

Slack completes a full directory sync, but later changes stay stale

Symptom
Initial sync populates users and groups, but subsequent member or user-group updates do not appear promptly.
Meaning
Slack realtime directory sync relies on Socket Mode: either the App-Level Token is missing or has the wrong prefix, Socket Mode is disabled, or the control plane cannot reach Slack outbound.
Fix
  1. Enable Sync directory changes on the IdP and supply a valid xapp- App-Level Token.
  2. Turn on Socket Mode in Slack and allow outbound internet connections from the control plane.
  3. Whenever you rotate the App-Level Token, update it in Ankole and test a fresh directory change.

Chat-channel troubleshooting

Chat channels receive inbound IM events and deliver Agent replies. Select the chat platform configured on your signal routing rule (which can differ from the platform you use for Console sign-in).

The Slack routing rule rejects a token prefix

Symptom
Saving the channel fails immediately with invalid_token_prefix before opening a connection.
Meaning
Either you swapped the Bot Token and App-Level Token fields, or pasted a different Slack token type.
Fix
  1. Ensure the Bot Token starts with xoxb- (copied from OAuth & Permissions).
  2. Ensure the App Token starts with xapp- and carries the connections:write scope.
  3. Fix both tokens and save again before debugging event delivery.

Slack direct messages work, but channel mentions do not

Symptom
The bot replies in direct messages, yet @mentions inside a channel never reach Ankole.
Meaning
Either the bot has not been invited to that channel, or the Slack app lacks the app_mention event subscription and app_mentions:read scope.
Fix
  1. Invite the bot into the target Slack channel.
  2. Subscribe to app_mention under Event Subscriptions and add the app_mentions:read Bot Token scope.
  3. Reinstall the Slack app after changing scopes and update the Bot Token in Ankole.

Slack delivers @mentions but not ordinary channel messages

Symptom
addressed_only works, yet switching to observe_all or may_intervene still delivers only explicit @mentions.
Meaning
Ankole’s routing rule can process only the events that Slack delivers, and your Slack app is still missing the message event subscription or history scope for that channel type.
Fix
  1. Confirm that addressed_only works end-to-end first.
  2. Add the matching message.* bot event and history scope for public or private channels from Quick start.
  3. Reinstall the Slack app, update the Bot Token if refreshed, and then switch the group-message mode.

If the failing boundary is still unclear

Reproduce the failure once while noting the exact timestamp, Agent UID, routing-rule name, Provider, and full UI error message. Next, pull only the control-plane and Worker log lines around that timestamp and locate the earliest error event.

Never share a Client Secret, Bot Token, App Token, model API key, raw environment dump, or unredacted config file—when filing an issue, attach redacted log excerpts alongside exact reproduction steps rather than a full log archive.