## TL;DR
The pipeline YAML has a syntax error: bad indentation, an unquoted colon, or a structural mistake. Validate it locally (a YAML linter or a dry-run upload), fix the reported line, and the upload succeeds.

## Error
```text
buildkite: pipeline upload failed: yaml parse error
```

## Steps
1. Validate locally: run the pipeline file through a YAML linter to get the exact line and column. Expected: the parser names the offending line.
2. Fix the usual suspects: inconsistent indentation, unquoted values containing colons, tabs instead of spaces, or a missing `steps:` key. Expected: the linter passes.
3. Check Buildkite-specific structure: each step needs its command and label fields in the right shape. Expected: the structure matches the pipeline schema.
4. Dry-run the upload: use the agent's pipeline upload dry-run mode to validate without affecting the build. Expected: the dry run accepts the file.
5. Commit and re-run. Expected: the pipeline uploads and the build starts.

## When to use
- `buildkite-agent pipeline upload` fails with a YAML parse error
- New or edited pipeline files
- Generated pipelines (check the generator's quoting)

## When not to use
- Uploads succeed but steps fail (runtime issue)
- Agent connectivity problems (different layer)

## Tool compatibility
- Buildkite pipeline YAML; `buildkite-agent pipeline upload`, YAML linters

## Variant phrasings
### buildkite yaml invalid
Lint it locally; the error line is usually an indentation or quoting slip.

### pipeline upload parse error generated yaml
Quote values with colons and keep indentation consistent in the generator.

## Why it happens
Pipeline upload parses the YAML strictly before the build exists, so any syntax slip aborts the whole upload. Generated pipelines are the repeat offenders: template bugs emit subtly invalid YAML that looks fine to the eye.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_LjUXXm5keKKlhI3zuN-RtQ