buildkite: pipeline upload failed: yaml parse error

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

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