Troubleshooting

​

API Issues

​

”401 Unauthorized” errors

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

# 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

1. Check rate limit headers in response:
   Copy

   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

// 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

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
   Copy

   # 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

1. Heartbeat sent after expected interval
   Copy

   # 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
   Copy

   # 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

1. Check alert threshold: Default is 30 days. If cert expires sooner, you won’t get alerts
   Copy

   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

1. Test the channel
   Copy

   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

kodo webhooks get wh_abc123

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:
   Copy

   {
     "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

1. Verify DNS
   Copy

   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

1. Check CSP headers
   Copy

   Content-Security-Policy: script-src 'self' https://widget.kodostatus.com
   
2. Verify API key in widget config
   Copy

   <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

1. Verify initialization
   Copy

   // Check Beacon is initialized
   console.log(Beacon.isInitialized()); // Should be true
   
2. Check for filtering
   Copy

   // 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
   Copy

   Beacon.captureException(new Error('Test error'));
   
4. Check environment: Development errors may be filtered by default

​

Source maps not resolving stack traces

1. Verify upload succeeded
   Copy

   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
   Copy

   Beacon.init({ release: '1.2.3' });
   

​

CLI Issues

​

”Command not found: kodo”

1. Reinstall globally
   Copy

   npm install -g @kodo/cli
   
2. Check PATH
   Copy

   echo $PATH
   # Ensure npm global bin is included
   npm bin -g
   
3. Use npx
   Copy

   npx @kodo/cli incidents list
   

​

CLI not authenticated

# 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?

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