Bitbucket Runner Label Mismatch - runs-on Superset Rule

Bitbucket schedules a step on a runner only when the runner advertises every label in the step’s runs-on. Add a label to the step that no runner has, and the step can never match.

What this error means

A step queues forever even though a runner is online. The runner is missing one of the labels the step lists, so it is not a superset of the request and is skipped.

Step runs-on: [ self.hosted, linux, arm64 ]
Online runner labels: [ self.hosted, linux ]   # missing arm64 → no match

Common causes

Step requests a label no runner advertises

Every label in runs-on must be present on the runner. Adding arm64 to a step when no online runner advertises arm64 leaves the step unmatched.

Mismatched custom labels

A custom label on the step (gpu, prod) that does not exactly match what the runner was configured with breaks the subset relationship.

How to fix it

Request only labels the runner has

Trim runs-on to the labels an online runner actually advertises.

- step:
    runs-on:
      - self.hosted
      - linux
    script: [ ./build.sh ]

Add the missing label to a runner

1. Open Runners settings and review each runner’s labels.
2. Add the requested label to a runner, or remove it from the step.
3. Ensure at least one online runner is a superset of the step’s runs-on.

How to prevent it

• Keep runs-on to the minimum labels needed.
• Maintain a consistent label scheme across runners.
• Document which runners carry which custom labels.

Related guides