Troubleshooting
Common problems, what usually causes them, and how to fix them.
Slack
| Problem | Likely cause | Fix |
|---|---|---|
| No case threads appear | The bot is not in the case channel | Run /invite @Averil in the channel |
| Averil ignores my reply in a case thread | The reply did not mention Averil, so Slack did not send it | Reply again and mention @Averil |
| "Not set up to decide plans from Slack" | You are not on the approver list | Ask your admin to add you, or decide in the console |
| No Approve button on a plan | The plan is high risk | An admin approves it in the console with a passkey |
| Accept risk sends me to the console | Accepting risk needs a reason and an end date | Give both in the console |
| Averil answers without company details | You are a guest, or not yet in the context map | Ask from a full member account, or wait for the next collection (every 6 hours) |
Integrations
| Problem | Likely cause | Fix |
|---|---|---|
| An integration shows Access revoked | The app was uninstalled, or the token or role was removed | Reconnect it. Averil works from its last snapshot and marks checks as pending access until then. |
| An integration shows Degraded | Sign-in failures, or a missing scope | Check the install still has every permission listed on its Connect page |
| A repository has no owner | No CODEOWNERS file | Add one, for example * @your-org/your-team |
| An owner is not matched to a Slack person | CODEOWNERS names a GitHub login, which is not matched to Slack yet | Name the owner by email in CODEOWNERS |
| A pushed secret was not flagged | The push created a new branch, which is not scanned yet | Rotate the secret anyway. Pushes to existing branches are scanned. |
| A case says a region is a blind spot | The region is not in your AWS settings, or CloudTrail is off there | Add the region, or turn on a multi-region trail |
Plans and fixes
| Problem | Likely cause | Fix |
|---|---|---|
| An approved plan did not run | Fixes are paused, the action is turned off, or the target is protected | The reason is on the case. The approval is not used up. |
| The plan needs approval again | A step changed, so the action hash changed | Approve the new version |
| The case stays in Verifying | The read-back was inconclusive | Averil retries. If it stays there, the thread says what it could not confirm. |
| A case went back to Awaiting human | The read-back failed | Read the thread for what did not match |
Companion and MCP
| Problem | Likely cause | Fix |
|---|---|---|
| Claude Code shows a Companion warning on every action | The daemon is not running | Start averild, then run averil ping |
| The Companion never warns about anything | No configuration file, or the repository is not on the allowlist | Run averil status and check the configuration with us |
averil hooks install refuses | Your hooks directory is shared with other repositories | Add --allow-shared-hooks-path if that is what you want |
| Your MCP client says unauthorized | You are not signed in, or the session expired | Sign in again from the client |
| Your MCP client is refused after signing in | Your organization is not linked to an Averil workspace yet | Contact us to link it |
| Your MCP client says too many requests | More than 60 requests a minute | Wait a minute and try again |
Still stuck? Email averil@averil.ai, or ask in your shared channel with the founders.
Stuck? Email averil@averil.ai or ask me in Slack.