## TL;DR
An unexpected value is either a new legitimate category or dirty data URIs list the distinct values in the column with counts, identify exactly which value the test rejected, and trace it to its source. Add the value to the schema.yml list only when it is a real new category with an owner; otherwise fix the mapping that produced it.

```text
dbt test error: accepted_values test failed with unexpected value error
```

## Use this when
- The check or run fails with this symptom: accepted_values fails and names an unexpected value in the column.
- You are working on a dbt model failing an accepted_values test 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 not_null or unique failure, where the problem is missing or duplicated values rather than an unlisted one instead.
- The error text names a different tool, stage, or root cause. Match the verbatim error first and use that skill.

## Steps
1. Run the compiled accepted_values test SQL and list distinct column values with counts from the built model. Verify: the rejected value and its row count are known
2. Trace the rejected value to the source system or the model mapping, checking for new categories, casing variants, or free-text entries. Verify: the value's origin is identified
3. Decide ownership: a real new category gets added to the accepted list with a note; a variant gets normalised in staging; junk gets fixed at the source. Verify: the value is classified and the fix layer is chosen
4. Apply the fix and rebuild the model so the built table reflects the mapping or the updated test. Verify: the rebuilt model carries the corrected values or list
5. Rerun the accepted_values test plus a distinct-values check to confirm no other unlisted values remain. Verify: the test passes and the distinct list matches the accepted list exactly

## Variant phrasings
### dbt accepted_values test failed unexpected value
The verbatim unexpected-value phrasing.
### dbt accepted_values new category schema yml
The new-category phrasing for extending the accepted list deliberately.
### accepted_values failing on casing variant dbt
The variant phrasing for casing and whitespace differences.

Compatibility: dbt Core 1.5 and later accepted_values generic tests

## Why it happens
The test compares the column's distinct values with a fixed list in schema.yml. Source systems add categories without notice, integrations introduce casing or whitespace variants, and mappings fall through to defaults, all of which appear as one unexpected value in the test output.

## Edge cases / pitfalls
- Add a staging normalisation step for case and whitespace so variants stop recurring.
- Review the accepted list quarterly. Categories retire as well as arrive, and stale entries hide real errors.

## Provenance

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