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.ymlis correctly referencing your self-hosted runner resource class, for example:
jobs:
build:
machine: true
resource_class: your-namespace/your-resource-classConfirm 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)