Buildkite "plugin failed to fetch" in CI

By Daniel Zoghalchali·Latchkey

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.

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

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

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.

Frequently asked questions

Related guides

References

• GitHub Actions documentation