Setting the skill. One moment.
Omnibus
Skill 45 of 200
Finds out why a data quality check failed or errored, looks at the rows it matched, and recommends the fix.
4 minutes · 793 words · 10 sections
Install
npx skills add PostHog/skills --skill debugging-failed-data-quality-checksnpx skills add PostHog/skills/plugin marketplace add PostHog/skillsThe first command installs just this skill, by the name in its SKILL.md; the second installs the whole repository.
A check run ends in one of four states. Read the state first, because it decides where the problem is:
| Status | Meaning | Where to look |
|---|---|---|
failed | The query ran and the assertion found bad data | The data, or the assertion itself |
errored | The query could not run, so nothing was judged | The error text (never a data problem) |
skipped | The subject is gone | Whether the table or view still exists |
passed | The assertion held | Nothing |
row_count and freshness checks judge observed_value, not failed_row_count.
A failed row_count means the count fell outside its bounds.
A failed freshness means the newest row is older than the limit.
failed or errored and the user wants to know whyNot published:authoring-data-quality-checks or auditing-warehouse-view-health) found a failing check or a blocked view and handed it off| Tool | Purpose |
|---|---|
posthog:data-quality-check-results | A check’s recent runs, with compiled_query, error and the config it ran |
posthog:execute-sql | Re-run a run’s compiled_query to see the failing rows |
posthog:data-quality-check-run | Run a check now |
posthog:data-quality-check-update | Fix an assertion or change its severity |
view-get | A view’s definition and status |
view-run-history | A view’s materialization runs and their errors |
view-run | Materialize a view again |
To find the failing checks, query system.information_schema.data_quality_checks for last_status IN ('failed', 'errored'), or system.information_schema.data_quality_health for a subject’s verdict.
Call posthog:data-quality-check-results for the check.
On the newest run, read:
status and errorcheck_config and check_severity: what the run asserted, which can differ from the check todaycompiled_query: HogQL that selects the failing rows. For row_count it returns the count instead, so judge that check by observed_value.audited_staged_refresh: true when the run was part of a gated audit of a refresh before it was published. An errored run can carry it too, so read status first.Retention clears compiled_query after 30 days.
For an older run, run the check again.
Run compiled_query with posthog:execute-sql.
An empty compiled_query means there is nothing to replay: retention cleared it, or a gated run could not read the view’s definition.
Look at what it matched before you report anything.
A failure means one of two things: the data is bad, or the assertion is wrong.
The rows tell you which.
When audited_staged_refresh is true, the query does not read the published table.
It holds the view’s definition in a WITH clause and reads the view’s source tables now.
The sources may have changed since the run, so the rows and the count can differ from the run.
A query that now returns zero rows does not prove that the refresh was clean.
Compare with failed_row_count on the run.
An errored run did not judge the data. Match the error text:
| Error text | Cause and fix |
|---|---|
The staged files could not be read, so this data was not audited. | The gate could not reach the refresh before publish. The refresh publishes without a verdict. Run the view again. |
Metric checks cannot audit staged data. | A metric check was part of a gated refresh. It runs on its own schedule instead. |
The check query returned no rows. | The aggregate query returned nothing. Run the check again and report it if it repeats. |
A check that reads another subject needs an initiator or author… | An automatic run of a custom_sql or relationships check has no user to run as. A manual run works. An edit to the check’s assertion makes the editor its author. |
| A HogQL or ClickHouse error | A column name typo, a type mismatch, or a query that ran out of time. Fix the config, or add lookback_hours. |
Two messages come with skipped: The subject was deleted. and The subject no longer resolves.
The table or view is gone.
Delete the check or point it at the replacement.
When the team turns on “Block materialization on failing checks”, a materialized view’s error-severity checks run on each refresh before it is published. If one fails:
Not published: (see view-run-history).Warn-severity checks never block a refresh.
Fix the cause, then prove it:
posthog:data-quality-check-update.
If the failure is real but must not block the refresh, change severity to warn.view-run to materialize it again.
Otherwise call posthog:data-quality-check-run.posthog:data-quality-check-results again and confirm the newest run passed.errored is never evidence of bad data, and passed on an empty table is not evidence of good data.custom_sql query can read other tables.
Read the query before you blame the subject.authoring-data-quality-checks: writing and choosing checksauditing-warehouse-view-health: finding failing materialized viewsFinds out why a data quality check failed or errored, looks at the rows it matched, and recommends the fix. Also covers a materialized view refresh that the data quality gate did not publish. Use when asked why a check is red, what rows failed, why a view shows "Not published", why a view's data is stale after a refresh, or how to get a blocked refresh published. Trigger terms: failed check, failing rows, errored check, data quality failure, not published, blocked materialization, unpublished refresh, check keeps failing.
The verbatim description from this skill’s front matter — the string an agent matches on to decide whether to load it.
main, last pushed 8 November 2026.SKILL.md, not by matching a directory convention. 2 distinct layouts observed: skills/omnibus/*/SKILL.md, skills/posthog/all/skills/*/SKILL.md.h1 and no skipped levels:.claude-plugin/marketplace.json by PostHog, declaring 6 plugins. It is read for editorial metadata only — never as the skill index, which is always the repository tree./PostHog/skills.md, and each skill at its own .md URL.