Buildkite: agents property inside matrix.adjustments breaks pipeline upload

TL;DR

Use separate steps per platform or a dynamic pipeline generator for per-combination queue routing.

Steps

1. [buildkite/skills]: putting agents: inside matrix.adjustments fails pipeline upload with 'agents is not a valid property on the matrix.adjustments configuration'. Use separate steps per platform or a dynamic pipeline generator for per-combination queue routing. Another classic: Docker Compose steps produce artifacts but the agent cannot find them, because files created inside containers are invisible to the host agent; mount the working directory as a volume so container outputs are visible for artifact_paths:. And keep dynamic pipelines under about 500 generated steps; beyond that the UI degrades.

When to use

You are seeing this: [buildkite/skills]: putting agents: inside matrix.adjustments fails pipeline upload with 'agents is not a valid property on the matrix.adjustments configuration'. Use this skill when you run into "Buildkite: agents property inside matrix.adjustments breaks pipeline upload".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Source: Two pipeline-config mistakes that produce confusing errors, from Buildkite's own skill guidance.

Verified resolution: [buildkite/skills]: putting agents: inside matrix.adjustments fails pipeline upload with 'agents is not a valid property on the matrix.adjustments configuration'. Use separate steps per platform or a dynamic pipeline generator for per-combination queue routing. Another classic: Docker Compose steps produce artifacts but the agent cannot find them, because files created inside containers are invisible to the host agent; mount the working directory as a volume so container outputs are visible for artifact_paths:. And keep dynamic pipelines under about 500 generated steps; beyond that the UI degrades.

Source URL: https://github.com/buildkite/skills/blob/HEAD/steering/pipelines.md