## TL;DR
The checkpoint failed because the expectation suite itself has problems (missing expectations, invalid configs) or the data genuinely violates the suite. Read the validation results to separate "suite is broken" from "data is broken," fix the suite with `suite edit` or update the expectations, then re-run the checkpoint.

```text
great expectations checkpoint validation failed: expectation suite
```

## Use this when
- A GX checkpoint run fails mentioning the expectation suite
- An agent validates data against a hand-written suite
- Previously passing validations start failing

## Not for this skill when
- Data docs wont render (thats the docs site)
- The store backend errors (thats the metadata store)
- The profiler crashes (thats profiling)

## Steps

1. Run validation verbosely and read which expectations failed:

```bash
great_expectations checkpoint run my_checkpoint --validation-result
```
Expected output: per-expectation results. Failures with `unexpected_count` are data problems; errors about the expectation config itself are suite problems.

2. If the suite config is broken, open it for editing:

```bash
great_expectations suite edit my_suite
```
Expected output: the suite opens in a notebook. Look for expectations referencing dropped columns or invalid kwargs; those fail the whole run, not just one check.

3. For data drift (suite fine, data changed), update the expectation to match the new reality deliberately:

```python
# example: widen an allowed range after a legitimate schema change
validator.expect_column_values_to_be_between("amount", min_value=0, max_value=1000000)
```
Expected output: the suite reflects current data. Dont just loosen bounds to make red go green; check why the data changed first.

4. Re-run the checkpoint and confirm green:

```bash
great_expectations checkpoint run my_checkpoint
```
Expected output: validation succeeds. If it still fails, the results JSON names the next broken expectation; iterate.

## Variant phrasings

### checkpoint fails but suite edit shows nothing wrong
The checkpoint may reference a different suite name than you think. Print the checkpoint config and check the `expectation_suite_name`.

### failures started after a data pipeline change
The data changed, not the suite. Treat the failures as the system working: investigate the pipeline diff before touching expectations.

## Why it happens
A checkpoint binds a suite to a data batch; failure means the binding produced violations. The two root causes need opposite fixes: a broken suite needs editing, broken data needs a pipeline fix. Agents usually reach for loosening the suite, which destroys the value of the check; the discipline is to prove the data is wrong before changing the expectation.

## Edge cases
- Suites versioned separately from pipelines drift silently; pin the suite version the checkpoint uses.
- `expectation_suite_name` typos produce "suite not found" rather than validation failure; read the error kind carefully.
- Very wide tables make the results JSON huge; filter to failed expectations when reading it.

## Provenance

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