"Upgrade your plan to unblock build"

Overview

The "Upgrade your plan to unblock build" message appears when CircleCI determines that a build cannot proceed under your current plan's credit or usage limits. This article covers the most common causes and how to resolve each one.

Common Causes

1. Re-running a build originally triggered on the Free Plan

Symptom: You recently upgraded to the Performance Plan, but see this error when attempting to re-run an older workflow.

Cause: Builds are associated with the plan that was active when they were first triggered. Re-running a workflow that originated under the Free Plan may still be evaluated against Free Plan limits, even after you've upgraded.

Resolution:

• Rather than re-running the existing workflow, trigger a new pipeline by pushing a new commit or manually triggering via the CircleCI UI or API.
• New pipelines will correctly reflect your current Performance Plan entitlements.

2. Free Plan credit exhaustion

Symptom: You are on the Free Plan and builds are blocked partway through the week.

Cause: Free Plan credits are allocated on a weekly basis and do not roll over. Once your weekly credit allotment is exhausted, builds will be blocked until credits renew.

Resolution:

• Check your remaining credits under Plan > Plan Overview in the CircleCI web app.
• Credits renew at the start of each week. See When will free credits renew? for the exact reset schedule.
• If you need to continue building before the reset, consider upgrading to the Performance Plan.

3. Self-hosted runner builds still being blocked by credit checks

Symptom: You have configured a self-hosted (machine) runner and updated your config.yml with your resource class, but builds are still blocked with a credit-related message.

Cause: In some cases, CircleCI's credit check runs before the system identifies that the job is assigned to a self-hosted runner, which does not consume credits. This can produce a misleading block message.

Resolution:

• Verify your config.yml is correctly referencing your self-hosted runner resource class, for example:

  jobs:
    build:
      machine: true
      resource_class: your-namespace/your-resource-class

• Confirm your runner is listed and active under Self-Hosted Runners in the CircleCI web app.
• If your config looks correct but builds are still blocked, open a support ticket — this may require investigation of your account's credit evaluation logic.

4. Unregistered user triggering a blocked pipeline

Symptom: A build triggered by an external contributor or unregistered user is blocked.

Cause: If your organization has enabled the Prevent unregistered user spend setting, pipelines triggered by users without a CircleCI account will be blocked from consuming credits.

Resolution:

• If the block is intentional, no action is needed — the setting is working as designed.
• If you want to allow the build, the triggering user should sign up for a CircleCI account and connect their VCS identity.
• Org admins can review or toggle this setting under Plan > Usage Controls.

Still seeing the error?

If none of the above matches your situation, please open a support ticket and include:

• Your organization name and plan type
• The pipeline or workflow URL where the error appears
• Whether the build was a re-run or a fresh trigger
• Your VCS provider (GitHub / Bitbucket / GitLab)

Additional Resources

• CircleCI Pricing
• Compare plans