> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acrity.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Troubleshooting
> Diagnose common issues with Connected Apps, credentials, connectors, API keys, webhooks, billing, and repository readiness.
Use this guide to diagnose common failures on your own. Most issues come from provider permissions, expired secrets, or configuration that drifted after a rotation.
Reviews and their status appear on the [operations dashboard](/en/guides/ops-dashboard). For per-run diagnostics — including why a specific review started, retried, or failed — open the [audit trail](/en/console/audit-trail).
Repositories, Webhooks, API keys, Credentials, Connectors, and the Audit Trail require a Workspace admin (platform admins also have access). These roles are fixed capability sets defined by Acrity, not organization-configurable.
## Triage flow
```mermaid theme={null}
flowchart TD
A[Something is not working] --> B{Where did it fail?}
B -->|Sign-in or repo access| C[Connected Apps]
B -->|Provider token or scope| D[Credentials]
B -->|Self-hosted runner| E[Connectors]
B -->|Outgoing notification| F[Outbound webhooks]
B -->|API automation| G[API keys]
B -->|Reviews blocked| H[Billing]
B -->|Review never ran| I[Repositories]
C --> Z[Open the audit trail for the failing run]
D --> Z
E --> Z
F --> Z
G --> Z
H --> Z
I --> Z
```
## Common issues
| Symptom | Likely cause | Action |
| ------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| Callback or authorization fails | Incorrect callback URL or app created in the wrong environment | Check the callback URL shown in your Acrity installation and update the app in the provider |
| Installation appears invalid | Permission removed or token revoked | Use **Reauthorize** in **Connected Apps** |
| Repository does not appear | App was not installed on that repository or organization | Adjust the installation in the provider, then sync again |
| PM comments are not posted | The PM integration is not linked to the repository, or lost permission | Review the link on the repository detail page |
Managing credentials requires a Workspace admin.
| Symptom | Likely cause | Action |
| ---------------------------------- | ------------------------------------------------------ | -------------------------------------------------------- |
| Credential invalid | Token expired, revoked, or has insufficient permission | Edit or rotate the credential, then use **Validate** |
| Repository has no readiness | A VCS or PM credential is missing | Open the repository detail page and link the credentials |
| Provider returns permission denied | Insufficient scope in the provider | Update permissions in the provider and validate again |
Managing connectors requires a Workspace admin.
| Symptom | Likely cause | Action |
| ---------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| Connector offline | Service stopped, network blocked, or token rotated | Check the local service, proxy, and installed secrets, then **Revalidate** |
| Private repositories do not appear | Local token lacks permission or the instance URL is incorrect | Review the local configuration and **Revalidate** |
| TLS or certificate error | Corporate proxy or untrusted CA | Configure the certificate chain required by your company |
| Revalidation fails after rotation | The new secret was not applied on the host | Update the local vault or environment, restart the connector, then **Revalidate** |
Managing webhooks requires a Workspace admin.
| Symptom | Likely cause | Action |
| ----------------------------- | ------------------------------------------------ | ----------------------------------------------------------- |
| `401` or `403` at destination | Invalid destination token or header | Update the secret headers in the webhook |
| Invalid signature | Different HMAC secret in Acrity and the receiver | Rotate the secret and test again |
| Timeout | Destination is slow or unavailable | Test the URL outside Acrity and review the receiver timeout |
| Payload rejected | Template incompatible with the destination | Use preview and test before activating |
Managing API keys requires a Workspace admin.
| Symptom | Likely cause | Action |
| ---------------------------------- | ------------------------------------------ | ----------------------------------------------------------- |
| `401` | Key missing, invalid, expired, or inactive | Confirm the `X-Acrity-Key` header, validity, and key status |
| `403` | Insufficient scope | Add the required scope or create a new key |
| `429` | Usage limit reached | Apply backoff and reduce concurrency |
| Integration stopped after rotation | The old secret is still in use | Update the vault and restart the automation |
| Symptom | Likely cause | Action |
| ---------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Reviews blocked by billing | Trial ended, wallet balance insufficient, or spend cap reached | Open **Billing** to top up the wallet or adjust the spend cap. Plan changes are handled by Acrity — contact support |
| Payment portal does not open | Your role cannot manage billing | Ask a Workspace admin or Billing Manager to complete the payment |
| Top-up does not appear | Payment is pending or failed | Check the wallet history and payment method |
Managing repositories requires a Workspace admin.
| Symptom | Likely cause | Action |
| ---------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| Review does not start | Webhook not configured, repository paused, or a branch rule ignores the change | Review the repository detail page, then confirm on the [operations dashboard](/en/guides/ops-dashboard) whether the review was queued |
| Comment does not appear in the PR or MR | Result posting disabled or insufficient permission | Validate the credential and the statuses/checks in the provider |
| Result appears in an unexpected language | Language override on the repository or workspace | Review the language setting on the workspace and repository detail page |
| Bootstrap unavailable | Repository is not eligible or setup is incomplete | Open the **Bootstrap** tab and follow the displayed guidance |
## When to contact support
Open a ticket with:
* the affected workspace and repository;
* the approximate time of the issue;
* the provider involved;
* a screenshot of the error with credentials removed;
* the review or scan identifier and run status from the [audit trail](/en/console/audit-trail) when available.
Never send tokens, API keys, HMAC secrets, or complete credentials in the ticket.