playbooks

home / skills / jeremylongshore / claude-code-plugins-plus-skills / posthog-common-errors

posthog-common-errors skill

/plugins/saas-packs/posthog-pack/skills/posthog-common-errors

This skill helps diagnose and fix common PostHog errors by pointing to documented solutions and verification steps.

npx playbooks add skill jeremylongshore/claude-code-plugins-plus-skills --skill posthog-common-errors

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.3 KB
---
name: posthog-common-errors
description: |
  Diagnose and fix PostHog common errors and exceptions.
  Use when encountering PostHog errors, debugging failed requests,
  or troubleshooting integration issues.
  Trigger with phrases like "posthog error", "fix posthog",
  "posthog not working", "debug posthog".
allowed-tools: Read, Grep, Bash(curl:*)
version: 1.0.0
license: MIT
author: Jeremy Longshore <[email protected]>
---

# PostHog Common Errors

## Overview
Quick reference for the top 10 most common PostHog errors and their solutions.

## Prerequisites
- PostHog SDK installed
- API credentials configured
- Access to error logs

## Instructions

### Step 1: Identify the Error
Check error message and code in your logs or console.

### Step 2: Find Matching Error Below
Match your error to one of the documented cases.

### Step 3: Apply Solution
Follow the solution steps for your specific error.

## Output
- Identified error cause
- Applied fix
- Verified resolution

## Error Handling

### Authentication Failed
**Error Message:**
```
Authentication error: Invalid API key
```

**Cause:** API key is missing, expired, or invalid.

**Solution:**
```bash
# Verify API key is set
echo $POSTHOG_API_KEY
```

---

### Rate Limit Exceeded
**Error Message:**
```
Rate limit exceeded. Please retry after X seconds.
```

**Cause:** Too many requests in a short period.

**Solution:**
Implement exponential backoff. See `posthog-rate-limits` skill.

---

### Network Timeout
**Error Message:**
```
Request timeout after 30000ms
```

**Cause:** Network connectivity or server latency issues.

**Solution:**
```typescript
// Increase timeout
const client = new Client({ timeout: 60000 });
```

## Examples

### Quick Diagnostic Commands
```bash
# Check PostHog status
curl -s https://status.posthog.com

# Verify API connectivity
curl -I https://api.posthog.com

# Check local configuration
env | grep POSTHOG
```

### Escalation Path
1. Collect evidence with `posthog-debug-bundle`
2. Check PostHog status page
3. Contact support with request ID

## Resources
- [PostHog Status Page](https://status.posthog.com)
- [PostHog Support](https://docs.posthog.com/support)
- [PostHog Error Codes](https://docs.posthog.com/errors)

## Next Steps
For comprehensive debugging, see `posthog-debug-bundle`.

Overview

This skill diagnoses and fixes common PostHog errors and exceptions quickly. It guides you from identification through targeted fixes and verification so you can restore analytics flow and integrations with minimal downtime.

How this skill works

The skill inspects error messages, logs, and request traces to match issues to a catalog of common PostHog failures (authentication, rate limits, timeouts, network errors, misconfiguration). For matched cases it returns concrete remediation steps, diagnostic commands, and verification checks. It also recommends escalation steps and resources when a local fix is insufficient.

When to use it

  • You see authentication failures or invalid API key errors in logs.
  • Events are not arriving or requests are being dropped due to rate limits.
  • SDK calls time out or you observe network-related failures.
  • Integration behavior changed after a deployment or config update.
  • You need a quick diagnostic checklist before contacting support.

Best practices

  • Always confirm environment variables and API keys with a simple env check or curl header test.
  • Implement exponential backoff and client-side rate limiting for bursty traffic.
  • Increase client timeouts only after ruling out network issues and server health.
  • Collect request IDs, SDK debug bundles, and logs before escalating to support.
  • Automate health checks that validate connectivity to PostHog endpoints.

Example use cases

  • Fixing 'Authentication error: Invalid API key' by validating environment vars and rotating keys.
  • Resolving 'Rate limit exceeded' by adding exponential backoff and queuing bursts.
  • Diagnosing 'Request timeout after 30000ms' by checking network, increasing client timeout, and retrying.
  • Verifying PostHog connectivity in CI by running simple curl and status checks before deployment.

FAQ

What should I check first when events stop appearing?

Verify your API key, confirm environment variables, and run a connectivity check (curl to API and status page). Collect a sample request ID if available.

When should I contact PostHog support?

After collecting logs, SDK debug bundle, request IDs, and confirming the issue isn’t client-side or due to rate limiting—then open a support ticket with that evidence.