Troubleshooting Slack

Most Slack problems in Chickpea are refusals: a check that did not pass, reported to the person who typed the message or on the Admin page you were working in. Where a crash loses work, a refusal keeps it: the Agent stays saved, the message stands, and one named condition has to change. This page lists the refusals and silences you are most likely to meet in Slack, each with its cause, its fix, and how to confirm the fix worked.

That Agent is not available here.

Sent as an ephemeral message that only you see, usually followed by Available here: @<handle>, @<handle>.

Cause. The Agent you mentioned has no active grant for this channel. The same refusal covers an Agent that is archived, disabled, or still a draft, a mention that does not resolve to exactly one Agent, and an actor Slack does not treat as a full workspace member. Multi-channel and single-channel guests are refused everywhere.

Fix. Publish the Agent to the channel. In Admin, open the Agent, use Slack channels → Add to channels, and pick the channel. If Chickpea lists the handles you expected, the Agent you mentioned is not published here. Publishing it hands that channel’s members everything it can do and reach.

Confirm. Mention the handle again in the channel and watch for a threaded reply under the Agent’s own name and avatar.

Mention one Agent at a time.

Cause. The message mentioned two Agent handles. Chickpea refuses rather than guesses, because the two Agents hold different accounts and answer for different channels.

Fix. Send one message per Agent. To move work between them, let the first Agent reply, then mention the second in that thread; the handover happens in the open and the new owner needs its own active grant.

Confirm. A single-handle mention gets a reply. If nothing at all appears, check whether SLACK_TAG_UNASSIGNED_HINT is set to false on the deployment: that silences this notice, so silence stops being evidence that the mention worked.

That Agent address could not be verified right now. Try again.

Cause. The mentioned user-group id was not in Chickpea’s stored Agent map, and Slack’s directory lookup failed or was rate limited. Chickpea neither answers nor guesses which Agent you meant.

Fix. Retry in a moment. If it keeps repeating, the user group is not one of Chickpea’s Agent handles, or its handle matches more than one Agent. Open the Agent in Admin and check the handle it holds.

Confirm. Mention the handle again. A successful lookup routes the turn normally and repairs the stored mapping, so the next mention is immediate.

A message at the top of a channel gets no reply

Cause. In every channel, a top-level message that mentions no one is dropped before any model is involved. There is no reply, no private notice, and no model call. Messages from other apps and bots, from Slack’s system users, and message edits are dropped the same way.

Fix. Address the message. Mention a handle that holds an active grant here, or mention @Chickpea.

Confirm. The addressed message gets a threaded reply. Nothing else in the channel is classified, so no other message will start a turn later.

A handle mentioned inside a thread gets no reply

Cause. The thread has no owner. A reply in a thread only starts a turn once an Agent owns that thread, and Chickpea drops the event before routing, so there is not even a private refusal.

Fix. Mention @Chickpea in the thread first. It answers in any channel the app has joined, as long as you are a member, and it takes ownership of the thread. Then mention the Agent you want, which hands the thread over to it. Starting a fresh channel message with the handle works too.

Confirm. @Chickpea replies in the thread, and the next mention of your Agent gets an answer from that Agent.

Slack blocked Chickpea from creating @support

Cause. Agent handles are Slack user groups, and a workspace may allow only Owners and Admins to create them. The Agent itself is saved; the handle is the only part that failed. Reconnecting Slack cannot repair a policy, so Chickpea does not suggest it.

Fix. Ask a Slack Workspace Owner or Admin to open Roles & permissions → Account types at slack.com/admin, choose Edit permission next to Create and edit user groups, add Members, and save. On Enterprise Grid an Org Owner sets the same permission under Organization settings → Roles & permissions. The change lets human members manage user groups too, so say that before you ask for it. A generic slack.com/admin link can open a different signed-in workspace, so confirm the workspace name first. Then open the Agent in Admin and choose Retry.

Confirm. Select the Agent’s real @handle in Slack’s mention picker and watch for a threaded reply in a channel that Agent is published to. Do not reinstall the app or create a second Agent.

Slack won’t create @support

Cause. Slack user groups require a paid Slack plan, and this workspace is not on one. The Agent is saved without a handle.

Fix. Upgrade the Slack workspace to a paid plan, then open the Agent in Admin and choose Retry.

Confirm. The handle appears in Slack’s mention picker, and mentioning it in a granted channel gets a threaded reply.

Join the Slack Channel before adding this Agent.

Cause. You are not a member of the channel you are publishing to. Slack channel membership is an independent ceiling that Admin authority cannot bypass, because publishing hands that channel’s members the Agent and every account behind it.

Fix. Join the channel in Slack, return to Admin, and choose Retry.

Confirm. The channel appears under the Agent’s Slack channels, and a mention in it gets a threaded reply.

Invite Chickpea to this private Channel

The refusal reads Invite Chickpea to the private Slack Channel before retrying.

Cause. Slack does not let apps join private channels themselves. Chickpea saves the channel grant as pending and stops there, so the Agent never answers in that channel yet.

Fix. In the private channel, run /invite @Chickpea. Then return to the Agent in Admin and choose Retry, which joins the reconciliation back up and flips the grant to active.

Confirm. The grant no longer reads pending in Admin, and mentioning the handle in that private channel gets a threaded reply.

The Agent asks you to reconnect Slack before it can read a file

The Agent reports the next action in its own words, from Reconnect Slack to grant the current file access permission, then retry.

Cause. Slack refused the file read for a missing scope or a broken installation binding. Chickpea’s required bot scopes come from the committed manifest, which includes files:read; installations that predate that scope must reconnect once.

Fix. On Add to Slack, open Settings → Slack and choose Reconnect with Slack, which refreshes the authorization without changing Agents, channel grants, or saved settings. On Use your own Slack app, repair the installation with the scoped recovery flow described below, which refuses any candidate credential missing a required scope.

Confirm. In Settings → Slack, choose Test connection and look for Connection healthy · <workspace name>. Then upload the file again and ask the Agent about it. Attachment turns stay read-only either way: a file can inform an answer, never authorize an action.

Verify Slack Events never completes

Setup stays on Verify Slack Events, with the status The candidate remains inactive until signed Events proof succeeds.

Cause. Slack has not delivered its signed challenge for this exact app and workspace. Chickpea promotes the encrypted credential revision only after the OAuth result and a revision-bound signed challenge agree, so an unverified Events URL leaves the credential inactive rather than half-installed.

Fix. Open Event Subscriptions for the app, choose Retry beside the Request URL, then Save Changes, and select Check signed Events verification again. In the manual lane, adopt the app credentials before attempting verification: without the signing secret Chickpea cannot authenticate Slack’s challenge, and the fourth credential field is the Signing Secret, not the Client Secret.

Confirm. The setup page advances to Become the first Owner. If it instead reads Installation could not be verified, the inactive bot credential was discarded and the private setup state is kept only for inspection; create a fresh deployment setup link before another attempt.

Settings → Slack reads Reconnect required

Cause. The deployment no longer holds a usable Slack authorization. Test connection names which one failed.

Fix. For a binding or approving-member problem on Add to Slack, choose Reconnect with Slack in Settings → Slack as a current Slack Owner or Admin. For a rejected credential, a missing scope, or lost key material on Use your own Slack app, use the scoped credential recovery flow. Put a new random 32-byte CHICKPEA_RECOVERY_TOKEN in the deployment secret store, then run the read-only preflight:

CHICKPEA_RECOVERY_TOKEN='<32-byte random value>' \
  npm run auth:recover -- --url <https://your-deployment>

On Node, add --state-db <path to tag-state.db> to check the expected app, workspace, credential revision, and health gate without changing state. The preflight prints the exact /admin/recovery URL, a route deliberately absent from normal navigation. It mints one browser-bound session for 15 minutes, takes the existing app ID, workspace ID, client ID, client secret, and signing secret as write-only fields, and promotes the repaired revision only after signed Events proof. Delete or replace CHICKPEA_RECOVERY_TOKEN afterwards.

Confirm. Test connection returns Connection healthy · <workspace name> and the workspace badge reads Connected. Then mention an Agent in a granted channel and watch for a threaded reply.

Next steps

• Conversations: how a message reaches an Agent, and everything Chickpea ignores.
• Handles and channel grants: how a handle is made, what a grant stores, and who can DM an Agent.
• Set up your own Slack app: the setup path the Events and credential entries belong to.
• Security: how Slack client, signing, and bot secrets are stored and recovered.