Buildkite "Failed to upload pipeline" in CI

By Daniel Zoghalchali·Latchkey

The buildkite-agent pipeline upload command sends your steps to the Buildkite API. If the payload is structurally invalid or the API rejects it, the upload fails and no steps are added to the build.

What this error means

The upload step exits non-zero with "Failed to upload pipeline" and an explanation such as an unknown step attribute or an invalid structure.

$ buildkite-agent pipeline upload
2026-06-30 12:00:01 FATAL Failed to upload pipeline: Unknown attribute "commnd" on step 1

Common causes

A misspelled or unknown step attribute

A typo like commnd instead of command, or an attribute Buildkite does not recognize, makes the API reject the whole pipeline.

An invalid dynamic pipeline payload

A script that generates the pipeline emitted malformed YAML or JSON (empty output, wrong nesting), so the upload has nothing valid to send.

How to fix it

Validate the uploaded document

1. Print the exact document you pipe into pipeline upload and read the reported attribute.
2. Fix the misspelled key or invalid structure.
3. Re-run the upload; a clean exit means the steps were accepted.

# see exactly what is uploaded
cat .buildkite/pipeline.yml | buildkite-agent pipeline upload

Guard a generated pipeline

When generating steps dynamically, fail the generator on empty output before piping to upload so a silent generator bug is caught.

set -euo pipefail
./scripts/gen-pipeline.sh | tee /dev/stderr | buildkite-agent pipeline upload

How to prevent it

• Dry-run pipeline uploads in review to catch unknown attributes.
• Validate generator output is non-empty before uploading.
• Keep step keys spelled exactly as Buildkite documents them.

Frequently asked questions

Related guides

References

• GitHub Actions documentation