how to fix great expectations checkpoint failed with unexpected rows error

TL;DR

Treat unexpected rows as data to inspect, not noise: pull the unexpected rows sample from the checkpoint result, find the shared pattern in those rows, and fix the pattern at the source or adjust the one expectation that misjudges valid rows. A checkpoint fails on the first failing expectation, so fix and rerun one expectation at a time.

how to fix great expectations checkpoint failed with unexpected rows error

Use this when

• The check or run fails with this symptom: the checkpoint result reports unexpected rows for one or more expectations.
• You are working on a Great Expectations checkpoint that stops on unexpected rows and the failure repeats on the same data or configuration.
• You need the failing rows, rule, or stage isolated before changing thresholds or code.

Not for this skill when

• A checkpoint that fails before any expectation runs, which is a configuration or connection problem instead.
• The error text names a different tool, stage, or root cause. Match the verbatim error first and use that skill.

Steps

1. Open the checkpoint result JSON or Data Docs page and name the exact expectation, column, and unexpected count behind the failure. Verify: one failing expectation is isolated from the checkpoint summary
2. Extract the unexpected rows sample and look for a shared value pattern, such as a new status code, a boundary value, or rows from one source. Verify: the unexpected rows share an identifiable pattern
3. Decide per pattern: new valid value means update the expectation set or map; invalid value means fix the producer and quarantine the bad rows. Verify: each pattern is classified as valid-but-unexpected or genuinely bad
4. Apply the fix and rerun only that expectation against the same batch to confirm the batch now passes or fails only on truly bad rows. Verify: the single-expectation rerun matches the classification decision
5. Rerun the full checkpoint on the next fresh batch and confirm the action list and notifications complete. Verify: the checkpoint finishes with success true end to end

Variant phrasings

great expectations checkpoint unexpected rows sample

The sample-inspection phrasing, focused on the partial unexpected list.

checkpoint failed validation result success false

The result-JSON phrasing users see in CI logs.

great expectations checkpoint fails on new data

The new-data phrasing, where valid new values trip an older suite.

Compatibility: Great Expectations 0.18 and 1.x checkpoints with SQL, Pandas, or Spark datasources

Why it happens

A checkpoint bundles many expectations and reports the aggregate as failed when any expectation finds rows outside its rule. The unexpected rows are usually a distribution the suite was not written for: new categories, widened ranges, or a producer change, and the checkpoint message alone does not say which.

Edge cases / pitfalls

• Result stores that truncate the unexpected list can hide the pattern. Query the batch directly when the sample looks random.
• Fixing every failing expectation in one edit makes regressions untraceable. Change one rule at a time.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_z2L4MmbML0wvqTb8OCyw