> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kodostatus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Solutions to common issues with Kodo Status

Having issues? Start here. This guide covers the most common problems and their solutions.

## API Issues

### "401 Unauthorized" errors

**Symptom**: API requests return `401 Unauthorized`

**Solutions**:

1. **Check your API key**: Ensure `X-API-Key` header is set correctly
2. **Verify the key exists**: Generate a new key in Dashboard → Settings → API
3. **Check for typos**: Copy the key directly from dashboard, don't type it
4. **Environment variables**: Ensure `KODO_API_KEY` is exported in your shell

```bash theme={null}
# Verify your API key works
curl -I "https://kodostatus.com/api/v1/services" \
  -H "X-API-Key: $KODO_API_KEY"

# Should return 200 OK, not 401
```

### "429 Too Many Requests" errors

**Symptom**: API requests return `429` after many calls

**Solutions**:

1. Check rate limit headers in response:
   ```
   X-RateLimit-Limit: 100
   X-RateLimit-Remaining: 0
   X-RateLimit-Reset: 1706097600
   ```
2. Implement exponential backoff in your code
3. Cache responses where appropriate
4. Upgrade plan for higher limits

```javascript theme={null}
// Exponential backoff example
async function fetchWithRetry(url, options, retries = 3) {
  for (let i = 0; i < retries; i++) {
    const response = await fetch(url, options);
    if (response.status !== 429) return response;

    const resetTime = response.headers.get('X-RateLimit-Reset');
    const waitMs = (resetTime * 1000) - Date.now() + 1000;
    await new Promise(r => setTimeout(r, Math.min(waitMs, 30000)));
  }
  throw new Error('Rate limit exceeded after retries');
}
```

## Monitoring Issues

### Uptime monitor showing false positives

**Symptom**: Monitor reports "down" when your service is actually working

**Causes & Solutions**:

1. **Firewall blocking Kodo IPs**
   * Whitelist Kodo's monitoring IPs (see Dashboard → Settings → Monitoring)
   * Or use a different URL that's publicly accessible

2. **Timeout too aggressive**
   ```bash theme={null}
   # If your endpoint is slow, increase timeout
   kodo monitors update mon_abc123 --timeout 30000  # 30 seconds
   ```

3. **Geographic routing issues**
   * Enable multi-region checks (requires failure from 2+ regions)
   * This prevents false positives from single-region network issues

4. **Rate limiting your endpoint**
   * Ensure your service allows the check interval you've configured
   * Don't rate-limit Kodo's User-Agent

### Heartbeat showing missed when job ran

**Symptom**: Cron job executed but heartbeat shows as missed

**Causes & Solutions**:

1. **Heartbeat sent after expected interval**
   ```bash theme={null}
   # If job runs every hour, set grace period
   kodo heartbeats create hb_abc123 --grace-period 300  # 5 min grace
   ```

2. **Network timeout during heartbeat send**
   ```bash theme={null}
   # Add retry logic to your cron job
   curl --retry 3 --retry-delay 5 \
     "https://kodostatus.com/api/heartbeat/hb_abc123"
   ```

3. **Wrong timezone in cron configuration**
   * Ensure cron server and Kodo use same timezone (or both UTC)

### SSL monitor not detecting expiration

**Symptom**: Certificate expired but no alert received

**Solutions**:

1. **Check alert threshold**: Default is 30 days. If cert expires sooner, you won't get alerts
   ```bash theme={null}
   kodo ssl update ssl_abc123 --warn 60
   ```

2. **Verify notification channels**: Ensure channel is enabled and tested

3. **Check spam folders**: SSL alerts might be filtered

## Notification Issues

### Slack notifications not arriving

**Symptom**: Incidents created but no Slack message

**Solutions**:

1. **Test the channel**
   ```bash theme={null}
   curl -X POST "https://kodostatus.com/api/v1/notifications/channels/ch_slack/test" \
     -H "X-API-Key: your_api_key"
   ```

2. **Check webhook URL**
   * Ensure Slack webhook URL is still valid
   * Recreate webhook in Slack if organization changed settings

3. **Verify event filters**
   * Check if channel is configured to receive the event type
   * Dashboard → Notifications → Edit Channel → Events

4. **Check Slack channel permissions**
   * Ensure the webhook can post to the target channel

### Webhooks failing

**Symptom**: Webhook shows "failed" in delivery history

**Check delivery logs**:

```bash theme={null}
kodo webhooks get wh_abc123
```

**Common issues**:

1. **Timeout**: Your endpoint takes too long
   * Kodo waits 30 seconds max
   * Return 200 immediately, process async

2. **SSL errors**: Your endpoint has invalid certificate
   * Ensure valid SSL on your webhook URL

3. **Authentication failing**: Your endpoint requires auth
   * Add auth headers to webhook config:
   ```json theme={null}
   {
     "headers": {
       "Authorization": "Bearer your_token"
     }
   }
   ```

4. **Wrong response code**: Your endpoint returns non-2xx
   * Kodo expects 200-299 for success
   * Check your server logs

## Status Page Issues

### Custom domain not working

**Symptom**: Custom domain shows error or wrong page

**Solutions**:

1. **Verify DNS**
   ```bash theme={null}
   dig status.yourdomain.com CNAME
   # Should point to your-org.kodostatus.com
   ```

2. **Wait for propagation**: DNS can take up to 48 hours

3. **Check SSL provisioning**
   * Dashboard → Settings → Custom Domain
   * SSL should show "Active"
   * If "Pending", wait or click "Retry"

4. **Clear browser cache**: Try incognito/private mode

### Widget not loading

**Symptom**: Status widget shows blank or error

**Solutions**:

1. **Check CSP headers**
   ```
   Content-Security-Policy: script-src 'self' https://widget.kodostatus.com
   ```

2. **Verify API key in widget config**
   ```html theme={null}
   <script src="https://widget.kodostatus.com/widget.js"
           data-api-key="your_public_key"
           data-slug="your-org">
   </script>
   ```

3. **Check browser console for errors**

## Beacon/Error Tracking Issues

### Errors not appearing in dashboard

**Symptom**: Beacon installed but no errors showing

**Solutions**:

1. **Verify initialization**
   ```javascript theme={null}
   // Check Beacon is initialized
   console.log(Beacon.isInitialized()); // Should be true
   ```

2. **Check for filtering**
   ```javascript theme={null}
   // Ensure you're not filtering all errors
   Beacon.init({
     apiKey: 'key',
     beforeSend: (event) => {
       console.log('Beacon event:', event);
       return event; // Must return event, not undefined
     }
   });
   ```

3. **Test with manual error**
   ```javascript theme={null}
   Beacon.captureException(new Error('Test error'));
   ```

4. **Check environment**: Development errors may be filtered by default

### Source maps not resolving stack traces

**Symptom**: Stack traces show minified code, not original

**Solutions**:

1. **Verify upload succeeded**
   ```bash theme={null}
   kodo sourcemaps list --release 1.2.3
   ```

2. **Check URL matches**
   * Uploaded URL must exactly match error URL
   * Including protocol (https\://) and path

3. **Ensure release matches**
   * Beacon release must match sourcemap release
   ```javascript theme={null}
   Beacon.init({ release: '1.2.3' });
   ```

## CLI Issues

### "Command not found: kodo"

**Solutions**:

1. **Reinstall globally**
   ```bash theme={null}
   npm install -g @kodo/cli
   ```

2. **Check PATH**
   ```bash theme={null}
   echo $PATH
   # Ensure npm global bin is included
   npm bin -g
   ```

3. **Use npx**
   ```bash theme={null}
   npx @kodo/cli incidents list
   ```

### CLI not authenticated

**Symptom**: "Not authenticated" errors

**Solutions**:

```bash theme={null}
# Login again
kodo auth login

# Or set API key directly
export KODO_API_KEY=your_api_key

# Or use config file
echo "api_key: your_api_key" > ~/.kodo/config.yml
```

## Still Stuck?

<CardGroup cols={2}>
  <Card title="Community Support" icon="discord" href="https://discord.gg/kodo">
    Ask questions in our Discord
  </Card>

  <Card title="Email Support" icon="envelope" href="mailto:support@kodostatus.com">
    Contact our support team
  </Card>
</CardGroup>

When reporting issues, include:

* Error messages (full text)
* API response bodies
* CLI version (`kodo --version`)
* Steps to reproduce