Buildkite "plugin failed to fetch" in CI

Before running a step, the agent clones each referenced plugin at its version tag. If the repository or ref cannot be fetched, the step fails with a plugin fetch error.

What this error means

A step fails during setup with "Failed to fetch plugin" naming the plugin and version, before the command runs.

buildkite

Failed to fetch plugin "docker-compose#v4.16.0":
git clone -- https://github.com/buildkite-plugins/docker-compose-buildkite-plugin.git ...
fatal: Remote branch v4.16.0 not found in upstream origin

Common causes

The pinned plugin version does not exist

The #vX.Y.Z ref is a typo or a version that was never tagged, so the clone cannot check it out.

The agent cannot reach the plugin source

A private plugin repo without credentials, or blocked egress to GitHub, prevents the clone from completing.

How to fix it

Pin an existing plugin tag

Confirm the plugin version tag exists in its repository.
Update the plugin reference to a real tag.
Re-run so the agent can fetch and run the step.

pipeline.yml

steps:
  - command: "make test"
    plugins:
      - docker-compose#v4.16.0:
          run: app

Allow access to private or self-hosted plugins

For a private plugin, give the agent git credentials for the plugin host, or vendor the plugin and reference it by a local path.

How to prevent it

Pin plugins to tags you have verified exist.
Give agents credentials for any private plugin repositories.
Vendor critical plugins to remove an external fetch dependency.