> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chevre.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Troubleshooting Common Issues — Chevre Help Center
> Diagnose and resolve the most common issues with Chevre authentication, workflows, integrations, and API errors using this step-by-step guide.
Most issues with Chevre fall into a small number of predictable categories. This guide walks you through how to diagnose each one systematically, with clear steps to resolve the problem or escalate to support if needed.
## Authentication Issues
### "401 Unauthorized" errors
A `401 Unauthorized` response means the API could not verify your identity. Work through the following steps in order to pinpoint the cause.
Go to **Settings → API Keys** and verify that the key you're using is listed. If it doesn't appear, it may have been deleted — generate a new one and update your application.
Chevre requires the API key to be sent as a Bearer token in the `Authorization` header:
```http theme={null}
Authorization: Bearer YOUR_API_KEY
```
A missing `Bearer ` prefix, extra whitespace, or an incorrectly named header are common causes of `401` errors.
In **Settings → API Keys**, check the **Status** column for your key. If it shows **Revoked**, generate a new key and update your integration. Keys are also invalidated immediately when rotated — if a rotation happened recently, retrieve the new key value.
Some endpoints require specific scopes (for example, `workflows:write` or `members:read`). Open the key's detail view in **Settings → API Keys** and confirm it includes the scope required by the endpoint you're calling. Edit the key to add missing scopes if needed.
***
### "403 Forbidden" errors
A `403 Forbidden` response means Chevre authenticated you successfully but your API key or user account does not have permission to perform the requested action.
Every API key is issued with a set of **scopes** that define which resources it can read or modify. If a key has the `workflows:read` scope but not `workflows:write`, any attempt to create or modify a workflow returns `403`.
To fix a scope mismatch:
1. Go to **Settings → API Keys** and open the affected key.
2. Review the assigned scopes and compare them against the [API reference](/api-reference) for the endpoint you're calling.
3. Add any missing scopes and save the key.
Workspace role permissions also apply. Even a key with broad scopes cannot take actions that your workspace role prohibits. Contact your workspace Owner if you need elevated permissions.
***
### Can't log in
If you can't access your account, try the following:
* **Reset your password.** On the login page, click **Forgot password?** and enter your email address. Chevre sends a reset link valid for 30 minutes.
* **Check your SSO configuration.** If your workspace uses Single Sign-On, confirm with your IT administrator that your SSO provider is correctly configured and that your account is provisioned in the identity provider. Mismatched email addresses between Chevre and your IdP are a common cause of SSO login failures.
* **Clear your browser cache and cookies.** Stale session cookies occasionally prevent successful logins. Try an incognito window to rule this out.
***
### 2FA locked out
If you've lost access to your two-factor authentication device, use one of the **backup codes** provided when you first enabled 2FA. On the login page, click **Use a backup code** and enter one of your saved codes.
Each backup code can only be used once. After using a backup code, log in and immediately regenerate your 2FA setup under **Settings → Security** to avoid future lockouts.
If you no longer have your backup codes, contact [support@chevre.io](mailto:support@chevre.io) from the email address associated with your account. Our team will verify your identity and help you regain access.
***
## Workflow & Automation Issues
### Workflow not triggering
If an automation isn't running when you expect it to, follow these steps to find the cause.
Open the automation in your project and confirm the toggle at the top of the page shows **Enabled**. A disabled automation ignores all incoming trigger events.
Open the trigger step and confirm the event type, source, and any filters match exactly what you expect. For example, a trigger set to fire on `task.completed` will not fire on `task.updated` — even if a task was updated to a completed status.
Go to **Run History** for the automation. If Chevre received the trigger event but the run failed before completing, you'll see a **Failed** entry with an error message. Use that message to diagnose the next step.
If your trigger relies on an external integration (for example, a webhook from a third-party app), go to **Settings → Integrations** and confirm the connection status shows **Connected**. A disconnected integration does not deliver trigger events to Chevre.
***
### Automation run failed
When a run fails, Chevre captures the full error context so you can debug it quickly.
1. Open the automation and click **Run History**.
2. Click on the failed run to expand its detail view.
3. Review the **error message** and the **failing step** — Chevre highlights exactly which action encountered the problem.
**Common causes and fixes:**
| Cause | Fix |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| Integration disconnected | Go to **Settings → Integrations** and reconnect the affected service. |
| Rate limit hit | Wait for the limit window to reset, or upgrade your plan for a higher limit. |
| Invalid template variable | Check that all `{{variable}}` references in your action fields match variables available from the trigger payload or previous steps. |
***
### Run history shows "Pending" indefinitely
A run stuck in **Pending** usually indicates a temporary queue backlog on Chevre's processing infrastructure.
Wait **5 minutes** and refresh Run History. In most cases the run will have completed or transitioned to a **Failed** status with an error message.
If the run remains **Pending** for more than 10 minutes, check [status.chevre.io](https://status.chevre.io) for any active incidents. If there are no reported incidents, contact [support@chevre.io](mailto:support@chevre.io) with your workspace ID and the affected run ID so our team can investigate.
***
## Integration Issues
### Slack integration not sending messages
If your Slack integration is connected but messages aren't being delivered, work through these checks:
1. **Re-authorize the Slack app.** Go to **Settings → Integrations → Slack** and click **Reconnect**. OAuth tokens occasionally expire or are revoked when Slack workspace admins change permissions.
2. **Verify the channel name is correct.** Channel names in Chevre are case-sensitive and must match exactly, without the `#` prefix (for example, `general`, not `#general`).
3. **Confirm the Chevre bot is invited to the channel.** The Chevre Slack bot can only post to channels it has been invited to. In Slack, open the target channel, type `/invite @Chevre`, and press **Enter**.
Use a **public channel** during initial setup to rule out permission issues. Once messages are flowing correctly, you can switch to a private channel after inviting the bot.
***
### Webhook not receiving events
If Chevre is sending webhook events but your endpoint isn't receiving them, check the following:
1. **Confirm your endpoint returns a `2xx` status code.** Chevre considers a delivery successful only when the endpoint responds with a status in the `200–299` range. Any other response causes Chevre to mark the delivery as failed and retry with exponential backoff.
2. **Verify the webhook secret is correct.** Open **Settings → Integrations → Webhooks**, view the secret for your endpoint, and confirm your application is using the same value to validate the `X-Chevre-Signature` header.
3. **Check your firewall allows traffic from Chevre's IPs.** If your endpoint is behind a firewall or security group, ensure it allows inbound HTTPS traffic from Chevre's published IP ranges. Contact [support@chevre.io](mailto:support@chevre.io) to get the current list of egress IPs.
***
## API Issues
### Rate limit exceeded (429)
When you exceed your plan's rate limit, the API returns `429 Too Many Requests` with a `Retry-After` header. The header value is the number of seconds to wait before making another request.
Implement an **exponential backoff with retry** strategy in your client to handle `429` responses gracefully:
```javascript theme={null}
async function callWithRetry(url, options, maxRetries = 3) {
for (let attempt = 0; attempt < maxRetries; attempt++) {
const res = await fetch(url, options);
if (res.status !== 429) return res;
const retryAfter = res.headers.get('Retry-After') || 60;
await new Promise(r => setTimeout(r, retryAfter * 1000));
}
}
```
This function respects the `Retry-After` value from the API and retries up to three times before giving up. Adjust `maxRetries` based on how critical the request is.
If you're consistently hitting rate limits, consider batching requests, caching responses, or upgrading to a plan with a higher limit. See the [API rate limits reference](/api-reference/rate-limits) for per-plan details.
***
### Unexpected 500 errors
A `500 Internal Server Error` indicates an unexpected failure on Chevre's side. These errors are typically transient.
1. **Check [status.chevre.io](https://status.chevre.io)** for any active incidents or degraded service notices that explain the errors.
2. **Retry the request** after 30–60 seconds. Most transient `500` errors resolve on their own within a few minutes.
3. **Report the issue** if the errors persist or if the status page shows no incident. Include the following in your support report:
* Your workspace ID (found in **Settings → General**)
* The full request and response, including headers
* The approximate time the errors started
***
## Contacting Support
If you've worked through the relevant section above and still can't resolve the issue, our support team is ready to help.
Send a detailed message to **[support@chevre.io](mailto:support@chevre.io)**. Our team typically responds within one business day, with priority response times for Pro and Enterprise plans.
Visit **status.chevre.io** to see real-time system status, ongoing incident updates, and historical uptime data for all Chevre services.
To help us resolve your issue as quickly as possible, include the following in your support request:
* **Workspace ID** — found in **Settings → General**
* **Full error message** — copy the exact text or attach a screenshot
* **Steps to reproduce** — a clear, numbered sequence of actions that triggers the issue
* **When the issue started** — the approximate date and time (including your timezone)
* **What you've already tried** — list any troubleshooting steps you've completed from this guide