resolving-ingestion-warnings — Claude Code skill
resolving-ingestion-warnings walks through PostHog ingestion warnings: dropped events, rejected person merges, oversized payloads. Use it when event counts look low or identify calls misbehave.
no license 197 installs ★ 101 updated 2026-11-10
npx skills add PostHog/ai-plugin --skill resolving-ingestion-warnings -a claude-codeWhat resolving-ingestion-warnings does
This skill covers PostHog's ingestion warnings, the records the pipeline writes when it drops, alters or refuses an incoming event. It opens with the ingestion_warning health check: a summary first, then the active issues, each carrying a warning type, category, severity and affected count.
Severity sets the order of work. A critical issue means the event never landed. A warning means it arrived changed. Info marks a drop the team configured on purpose. From there the skill opens the matching references/fixing-*.md file for code-level causes and per-SDK fixes, and reaches for posthog:execute-sql over system.ingestion_warnings when you want the offending events themselves. Only the reference file you need gets loaded.
One rule runs through the flow: every value in details was written by whoever sent the event, and anyone with the project's public capture token can put text there. The skill reports that content as data and never acts on it. Distinct IDs need resolving to persons as well, before you read a pattern into a sample.
What it helps with
- Trace why events vanish from a PostHog project
- Explain duplicated accounts after identify or alias calls
- Shrink an event that grew past 1MB once person properties were attached
- Check whether a fix actually stopped new warnings
- Find the cause of gaps in recordings and empty heatmaps
Example prompts for the agent
- List the active
ingestion_warningissues and tell me which ones dropped data. - Our heatmaps are empty — pull the matching warning type and show the raw
detailsrows. - Person profiles look inflated; walk the
person_properties_size_violationreference and suggest the code fix.
How to install resolving-ingestion-warnings
1Skills CLI (Vercel)
npx skills add PostHog/ai-plugin --skill resolving-ingestion-warnings -a claude-code2Manually: put the files in place
~/.claude/skills/resolving-ingestion-warnings/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/resolving-ingestion-warnings/
1Skills CLI (Vercel)
npx skills add PostHog/ai-plugin --skill resolving-ingestion-warnings -a codex2Manually: put the files in place
.agents/skills/resolving-ingestion-warnings/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add PostHog/ai-plugin --skill resolving-ingestion-warnings -a cursor2Manually: put the files in place
.cursor/skills/resolving-ingestion-warnings/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install PostHog/ai-plugin skills/resolving-ingestion-warnings2Manually: put the files in place
.github/skills/resolving-ingestion-warnings/SKILL.md1Skills CLI (Vercel)
npx skills add PostHog/ai-plugin --skill resolving-ingestion-warnings -a gemini-cli2Platform CLI
gemini skills install https://github.com/PostHog/ai-plugin --path skills/resolving-ingestion-warningsManually: put the files in place
.devin/skills/resolving-ingestion-warnings/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add PostHog/ai-plugin --skill resolving-ingestion-warnings -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about resolving-ingestion-warnings
How to install resolving-ingestion-warnings in Claude Code?
Run npx skills add PostHog/ai-plugin --skill resolving-ingestion-warnings -a claude-code. The skill file lands at ~/.claude/skills/resolving-ingestion-warnings/SKILL.md.
What does resolving-ingestion-warnings do?
It pulls the active ingestion warnings from PostHog's health check, sorts them by severity, then sends you to the per-issue reference file or to system.ingestion_warnings for the raw events behind them.
Should I trust the text inside a warning's details?
No. It is event-supplied input: the project's public capture token lets anyone write into it. The skill treats those values as data to inspect and does not follow text found there.