## TL;DR
A Soda YAML parse failure is usually indentation, a duplicate key, or a SodaCL block the installed Soda version does not know: parse the file with a strict YAML loader first to separate YAML errors from SodaCL errors, then validate each block against the installed version's syntax. Fix the file in small steps, scanning after each, instead of rewriting it wholesale.

```text
agent couldn't parse soda yaml configuration error failed scan setup
```

## Use this when
- The check or run fails with this symptom: the Soda scan setup fails while parsing the YAML configuration.
- You are working on an agent failing to set up a Soda scan from its YAML configuration 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 scan that parses its configuration but cannot connect, which is a datasource problem instead.
- The error text names a different tool, stage, or root cause. Match the verbatim error first and use that skill.

## Steps
1. Load the YAML file with a plain YAML parser and capture the first structural error with its line number. Verify: the first YAML-level error and line are known
2. Fix structural issues: indentation inside check blocks, duplicate keys, and unquoted values containing special characters. Verify: the file loads as clean YAML
3. Run the Soda scan in a validate or dry mode to surface SodaCL-level errors block by block. Verify: SodaCL errors are separated from YAML errors
4. Compare any rejected block's syntax with the documentation for the installed Soda version, since SodaCL keywords change between versions. Verify: block syntax matches the installed version
5. Run the full scan and confirm every check executes, proving the configuration is fully usable. Verify: the scan runs all checks end to end

## Variant phrasings
### agent could not parse soda yaml configuration scan setup
The verbatim Soda YAML phrasing.
### soda yaml indentation duplicate key parse error
The structural phrasing for YAML-level faults.
### sodacl block syntax version mismatch configuration
The SodaCL-version phrasing for keyword changes.

Compatibility: SodaCL YAML configuration files parsed by agents and Soda Core

## Why it happens
Soda configurations mix two languages: YAML structure and SodaCL check syntax. An error in either stops setup with similar-looking messages, and agents that treat the file as opaque text cannot tell which layer failed, so they guess at rewrites that introduce new errors.

## Edge cases / pitfalls
- Quote values containing colons or special characters in check definitions; they are the most common silent YAML trap.
- Keep a minimal known-good configuration per Soda version to bisect against.

## Provenance

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