Skip to content
Skills Library
Data & analytics · Analysis

debugging-failed-data-quality-checks

/debugging-failed-data-quality-checks

Finds 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.

Repository
skills ↗
Licence
MIT
Last repository change
25.10.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Finds 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.

Triggers from the description

Not published
Original author description

Finds 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.

How it works

  1. When to use this skill
  2. Available tools
  3. Workflow
  4. Important notes
  5. Related
Original SKILL.md headings · 121 lines, 1,010 words
SKILL.md preview
---
name: debugging-failed-data-quality-checks
description: >
  Finds 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.
---

# Debugging failed data quality checks

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.

## When to use this skill

- A check or a subject shows `failed` or `errored` and the user wants to know why
- The user wants to see the rows a check matched
- A materialized view's latest run shows an error that starts with `Not published:`
- A view kept serving old data after a refresh, and the data quality gate is on
- Another skill (`authoring-data-quality-checks` or `auditing-warehouse-view-health`) found a failing check or a blocked view and handed it off

## Available tools

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

## Workflow

### Step 1: Read the run

Call `posthog:data-quality-check-results` for the check.
On the newest run, read:

- `status` and `error`
- `check_config` and `check_severity`: what the run asserted, which can differ from the check today
- `compiled_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.

### Step 2: Look at the failing rows

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.

### Step 3: Read an errored 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.

### Step 4: Understand a blocked refresh

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:

- The view's run shows an error that starts with `Not published:` (see `view-run-history`).
- The previous version of the view keeps serving queries.
- Downstream views in the same DAG are skipped for this run.
- The view's schedule is not paused.
  The next scheduled refresh runs the checks again.

Warn-severity checks never block a refresh.

### Step 5: Recover

Fix the cause, then prove it:

1. Fix the upstream data, or fix the assertion with `posthog:data-quality-check-update`.
   If the failure is real but must not block the refresh, change `severity` to `warn`.
2. For a blocked view, call `view-run` to materialize it again.
   Otherwise call `posthog:data-quality-check-run`.
3. Read `posthog:data-quality-check-results` again and confirm the newest run passed.

## Important notes

- Do not change a check's severity or assertion only to turn it green.
  Confirm with the user first.
- `errored` is never evidence of bad data, and `passed` on an empty table is not evidence of good data.
- A check reports against its subject, but a `custom_sql` query can read other tables.
  Read the query before you blame the subject.

## Related

- `authoring-data-quality-checks`: writing and choosing checks
- `auditing-warehouse-view-health`: finding failing materialized views

Versions

The database has no other skills named debugging-failed-data-quality-checks.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 574f5c442ef3 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100auditing-warehouse-view-health
    Audit the health of a PostHog project's materialized views (saved queries) — find every failed materialization and flag unused or stale materialized views that cost storage and compute. Use when the user asks "which of my views are broken?", "why is this materialized view…
  • 100data-quality-checker
    Implement data quality checks, validation rules, and monitoring. Use when ensuring data quality, validating data pipelines, or implementing data governance.
  • 100data-quality
    Use when validating a dataset or building quality checks into a pipeline. Covers profiling, schema and constraint validation, freshness and completeness checks, anomaly detection, and failing a pipeline correctly. Trigger on "this metric looks wrong", "add checks to the…
  • 100soda
    Soda Core is an open-source data quality engine that verifies data contracts, YAML files of checks (row count, freshness, missing, duplicate, invalid, schema, failed rows), against a warehouse table. Use when a user asks to test data quality, write Soda checks or contracts,…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.