Buildkite "meta-data get: key not found" in CI

Build meta-data is a per-build key/value store. meta-data get fails with "key not found" when the key was never set earlier in the same build, or a default was not provided.

What this error means

A step fails with "meta-data get: key not found" for a key it expected an earlier step to have set.

buildkite-agent

$ buildkite-agent meta-data get "release-version"
2026-06-30 12:00:01 FATAL Failed to get meta-data: key "release-version" not found

Common causes

The key was never set in this build

The producing step ran meta-data set on a different key, was skipped, or ran after the consumer, so the key does not exist yet.

No default was supplied for an optional key

meta-data get errors on a missing key unless you pass --default, so an optional value that was not set fails the step.

How to fix it

Set before get and order steps

Ensure the step that runs meta-data set completes before the consumer, with a wait if needed.
Use the exact same key name in set and get.
Re-run so the key exists when it is read.

pipeline.yml

steps:
  - command: "buildkite-agent meta-data set release-version 1.4.2"
  - wait
  - command: "buildkite-agent meta-data get release-version"

Provide a default for optional keys

Pass --default so an unset optional key returns a fallback instead of failing the step.

Terminal

buildkite-agent meta-data get "release-version" --default "0.0.0"

How to prevent it

Set meta-data in an earlier step and gate consumers with wait.
Use --default for keys that may not be set.
Keep meta-data key names consistent across steps.