mongo-ai/posthog-selfhosted-diagnosis

Self-hosted diagnosis workflow

Before you diagnose: fetch live docs

1. Run docs-search("self-hosted troubleshooting {specific symptom}")
2. Run docs-search("self-hosted deployment {docker OR helm OR kubernetes}")
3. If potential known bug: run gh search issues --repo PostHog/posthog "self-hosted {symptom}"
4. Use the fetched docs as your primary reference

The golden rule

PostHog support helps with PostHog configuration. Customer infrastructure (Kubernetes clusters, Docker hosts, cloud provider settings, networking) is the customer's responsibility.

Be helpful and point them in the right direction, but be clear about boundaries. Don't guess at infrastructure fixes you can't verify.

Step 0: Determine deployment type

| Signal | Deployment type | |--------|----------------| | "docker compose" or "docker-compose.yml" | Docker Compose (hobby/small) | | "helm", "kubernetes", "k8s", "EKS", "GKE", "AKS" | Kubernetes / Helm | | "posthog cloud" or no mention of self-hosting | Cloud — wrong skill, use standard diagnosis |

If unclear, ask: "Are you using PostHog Cloud (app.posthog.com / eu.posthog.com) or a self-hosted deployment?"

Step 1: Check instance health

Ask the customer to check:

• Instance status page: {their-posthog-url}/_health or /api/projects/
• ClickHouse status: Check if ClickHouse container/pod is running
• Postgres status: Check if Postgres is accepting connections
• Redis status: Check if Redis is responding to PING
• Kafka status (if applicable): Check consumer lag

For Docker Compose:

docker compose ps       # All containers should be "Up"
docker compose logs -f  # Check for error patterns

For Kubernetes:

kubectl get pods -n posthog    # All pods should be Running/Ready
kubectl logs -n posthog <pod>  # Check for errors

Step 2: Classify the self-hosted issue

| Symptom | Likely cause | Category | |---------|-------------|----------| | "No events coming in" | Ingestion pipeline, reverse proxy, or SDK config | PostHog + Infra | | "Events arrive but queries are slow" | ClickHouse resource limits or schema issues | Infra | | "Session replay not working" | Recording config, MinIO/object storage, or CSP | PostHog + Infra | | "Feature flags not evaluating" | API endpoint not reachable, or /decide blocked | PostHog + Infra | | "Can't log in / SSO broken" | Auth config, Postgres, or network issues | Infra | | "Upgrade failed" | Migration issues, version compatibility | PostHog + Infra | | "Out of disk / memory" | Resource limits, ClickHouse data growth | Infra | | "CORS / CSP errors" | Reverse proxy misconfiguration | Infra | | "SSL certificate errors" | Certificate config, proxy termination | Infra |

Step 3: Common self-hosted issues

Reverse proxy / CORS / SSL

The most common self-hosted issue. Run: docs-search("self-hosted reverse proxy CORS configuration")

Key checks:

• Is the reverse proxy (nginx, Caddy, Traefik) forwarding WebSocket connections? Session replay and live events need WebSocket support.
• Is the Host header being passed through correctly?
• Are CORS headers configured to allow the customer's app domain?
• Is SSL termination happening at the proxy or at PostHog?

ClickHouse resource issues

ClickHouse is the most resource-hungry component.

Common patterns:

• OOM kills: ClickHouse container/pod restarting → needs more memory
• Slow queries: Check system.query_log for long-running queries
• Disk full: ClickHouse data grows fast → check retention settings, add more disk, or configure TTL

Ask:

• "How much memory is allocated to ClickHouse? (Recommend minimum 4GB, 8GB+ for production)"
• "How much disk space is available? Check df -h on the ClickHouse data volume"

Event ingestion failures

If events aren't arriving:

1. Check if the Kafka consumer is running and processing
2. Check for ingestion warnings in PostHog (if UI is accessible)
3. Verify the SDK is pointed at the correct self-hosted URL (not app.posthog.com)
4. Check the reverse proxy logs for blocked requests

Upgrade / migration failures

Run: docs-search("self-hosted upgrade migration troubleshooting")

Common issues:

• Async migrations stuck: Check the async migrations page in PostHog UI (Settings → Instance Status → Async Migrations)
• Version skipping: PostHog sometimes requires sequential upgrades (can't skip major versions)
• Schema mismatch: ClickHouse schema not matching expected state after upgrade

Step 4: Search known self-hosted issues

gh search issues --repo PostHog/posthog "self-hosted {symptom}" --limit 10
gh search issues --repo PostHog/posthog "self hosted {alternate terms}" --limit 10

Also check the self-hosted docs:

gh api repos/PostHog/posthog.com/contents/contents/docs/self-host --jq '.[].name'

Step 5: Determine support boundary

In scope for PostHog support:

• PostHog configuration and settings
• SDK configuration pointed at self-hosted instance
• PostHog upgrade guidance and migration issues
• Feature configuration (flags, replay, experiments)
• Explaining PostHog's infrastructure requirements
• Known bugs in PostHog that affect self-hosted

Out of scope (customer's responsibility):

• Kubernetes cluster management and troubleshooting
• Docker host configuration and resource allocation
• Cloud provider settings (AWS, GCP, Azure)
• Network configuration, firewalls, load balancers
• SSL certificate management
• Database administration (Postgres tuning, ClickHouse optimization)
• Backup and disaster recovery

How to communicate the boundary:

DO: "PostHog needs at least 4GB of memory for ClickHouse to run smoothly. It looks like your deployment might be hitting resource limits. Here's our infrastructure requirements doc: [link]. Your DevOps team can use this to right-size the deployment."

DON'T: "That's an infrastructure issue, not our problem." or attempting to debug their Kubernetes cluster configuration.

Step 6: Consider Cloud recommendation

If the customer is struggling with self-hosted complexity, it's appropriate to gently suggest PostHog Cloud:

"If managing the infrastructure is becoming a challenge, PostHog Cloud handles all of this automatically and includes the same features. Happy to help you evaluate whether Cloud might be a better fit — you can migrate your data over."

Only suggest this when:

• The issue is primarily infrastructure, not PostHog
• The customer has expressed frustration with self-hosted maintenance
• The customer isn't on self-hosted for compliance/data residency reasons

Escalation

Escalate to engineering when:

• A PostHog bug specifically affects self-hosted but not Cloud
• Migration/upgrade is stuck and the documented steps don't resolve it
• Data corruption or loss in ClickHouse/Postgres
• A security issue specific to the self-hosted deployment