Skip to content
Ankole

FAQ and troubleshooting

This page is not a product overview and does not repeat each provider setup guide. Find the earliest failed boundary, then select the relevant identity or chat provider. Quick start remains the source of truth for installation and first-time setup.

Find the failed boundary

What you observe Check first
/setup or the Console does not open Deployment, control plane, DNS, and HTTPS
The Console opens, but sign-in fails or the directory is incomplete Identity Provider (IdP)
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. Provider setup has not started yet.
Meaning
The control plane is not healthy, or DNS, the reverse proxy, or the Ingress does not send traffic to it. Later Provider errors are usually consequences.
Fix
  1. Check the control plane, PostgreSQL, and reverse proxy. Fix the first error in the logs.
  2. If direct control-plane access works, check DNS, TLS, and the proxy target.
  3. Do not delete the database or persistent volume. A startup failure does not prove data damage.
Check the deploymentRead the logs

Where is the activation code for first-time setup?

Symptom
/setup asks for the activation code, but the startup terminal is closed or the code is lost in the logs.
Meaning
The control plane uses this code only for first-time setup. It expires after the first administrator signs in.
Fix
  1. If setup is not complete, select your deployment method in Quick start and use the log command in that tab.
  2. Search for SETUP ACTIVATION CODE. Do not guess the code from browser storage or database rows.
  3. If the instance already has a root administrator, sign in through the configured IdP instead of activating it again.
Read the activation code

Why is an enabled adapter still missing from the Provider list?

Symptom
The Control Plane Plugin is saved as enabled, but its option does not appear on the identity or signal-routing page.
Meaning
The control plane loads the plugin set at startup. Saving schedules the plugin for the next start; it does not add supervised work and configuration keys to the running process.
Fix
  1. Restart only the control plane. Do not remove data or restart PostgreSQL.
  2. After it starts, confirm that the plugin is active and return to the Provider page.
  3. If the control plane does not start, fix the first plugin initialization error in its logs.
Enable Plugins in Agent Library

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

Symptom
Channels, direct messages, and a second chat app all fail. A direct Agent conversation in the Console also fails.
Meaning
When the Console path also fails, the shared downstream path is the likely fault: the LLM Provider, Agent model profiles, or Worker, not one platform event permission.
Fix
  1. Confirm that the LLM Provider is enabled and that its credential and model names work.
  2. Confirm that the Agent has primary, light, and heavy profiles and that at least one Worker is ready.
  3. Complete one real model conversation in the Console, then return to the selected chat-platform tab.
Configure the LLM Provider and AgentWorker fleet

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

Symptom
The schedule exists, but it did not start at the expected time, or its next run does not match your expectation.
Meaning
The schedule can be disabled, the instance timezone or cron expression can be wrong, or the control plane was not running at trigger time.
Fix
  1. Open the schedule, confirm that it is enabled, and inspect the displayed next run.
  2. Check the instance timezone and cron expression. Use the time shown by the Console instead of estimating from the expression.
  3. Select Run now. If it works, correct the time settings. If it fails, inspect the run record.
Configure and inspect schedules

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

Symptom
A run record exists, but the target chat or conversation did not receive an Agent message.
Meaning
The trigger worked. The fault is later in the path: the target route, Channel Provider, Agent models, or an available Worker.
Fix
  1. Open the run record, confirm its outcome, and read the first error.
  2. Check the target Agent, conversation or chat destination, and its signal routing rule.
  3. Confirm that the Agent model profiles work and that at least one Worker is ready.
Inspect schedule runsCheck signal routing rules

Identity Provider troubleshooting

The IdP owns sign-in, contacts, and organization sync. Select the identity source that your enterprise uses. Slack Socket Mode, Entra ID Graph subscriptions, and Google Workspace full sync are different mechanisms and require different checks.

Slack sign-in fails during the authorization redirect

Symptom
Slack reports a redirect_uri mismatch before it returns to Ankole, or authorization returns to the wrong page.
Meaning
The Slack Redirect URL does not exactly match the callback shown by /setup, or Ankole contains a Client ID from another app.
Fix
  1. Copy the full callback from /setup into OAuth & Permissions → Redirect URLs.
  2. Compare the scheme, host, port, path, and Provider ID character by character.
  3. Save the Slack app and start a new sign-in from Ankole. Do not reuse the old authorization page.

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

Symptom
The administrator enters the Console, but Principals or permission groups are empty or miss recent members.
Meaning
The identity app lacks users:read, users:read.email, or team:read; its Bot Token predates the new scopes; or the full sync has not run.
Fix
  1. Add the identity scopes listed in Quick start.
  2. After a scope change, install the app to the workspace again and save the new Bot Token in the IdP.
  3. Verify a full sync before you troubleshoot realtime sync.

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

Symptom
The first sync has data, but member or user-group changes do not appear promptly.
Meaning
Realtime sync uses Socket Mode. The App Token is missing, has the wrong prefix, Socket Mode is off, or the control plane cannot reach Slack.
Fix
  1. Enable realtime sync in the IdP and provide a valid App Token.
  2. Enable Socket Mode in Slack and allow outbound internet access from the control plane.
  3. After App Token rotation, update the value in Ankole and test a new directory change.
Configure the Slack IdP in Quick start

Chat-channel troubleshooting

The chat channel receives IM messages and sends Agent replies. Select the platform in the routing rule. The platform used for the IdP does not change this choice.

The Slack routing rule rejects a token prefix

Symptom
Saving the channel returns invalid_token_prefix before a connection opens.
Meaning
The Bot Token and App Token are reversed, or one value is another Slack token type.
Fix
  1. The Bot Token must start with xoxb- and come from OAuth & Permissions.
  2. The App Token must start with xapp- and include connections:write.
  3. Correct the values and save again. Do not troubleshoot events before credential validation passes.

Slack direct messages work, but channel mentions do not

Symptom
The bot answers a direct message, but an explicit @mention in a channel never reaches Ankole.
Meaning
The bot is not a channel member, or the app does not subscribe to app_mention with app_mentions:read.
Fix
  1. Invite the bot to the test channel.
  2. Add app_mention under Event Subscriptions and grant app_mentions:read.
  3. After a scope change, install the app again and update the Bot Token in Ankole.

Slack delivers @mentions but not ordinary channel messages

Symptom
addressed_only works, but observe_all or may_intervene still sees only explicit mentions.
Meaning
The routing rule controls messages that Ankole receives. The Slack app still lacks the matching message event or history scope for that conversation type.
Fix
  1. First verify the complete addressed_only path.
  2. Add the message event and history scope for the target conversation type as shown in Quick start.
  3. Install the app again, update the token, and then change the group-message mode.
Configure the Slack channel in Quick start

If the failing boundary is still unclear

Reproduce the fault once. Record the exact time, Agent UID, routing-rule name, Provider, and full error shown by the interface. Then collect only the control-plane and Worker logs around that time, and find the first error by event name.

Do not send a Client Secret, Bot Token, App Token, model API key, full environment dump, or unredacted configuration file. When you report an issue, include redacted logs and exact reproduction steps instead of a complete log archive.