Diagnosing and Fixing Resource Class and Credit Exhaustion Failures in CircleCI Pipelines

Problem Overview

When a CircleCI workflow stops before any job begins, the UI often shows a red banner with the text "Insufficient Credits" or "Unsupported resource class". These errors arise from two related but distinct limits: the organization’s monthly credit quota and the resource class you request in .circleci/config.yml. The following guide walks through the most common symptoms, the root causes, and the steps you can take to resolve them.

Common Symptoms

• Jobs fail to start, never reaching the first command in the script block.
• Failure messages contain phrases like "Credit limit reached" or "Resource class not available".
• The pipeline status remains queued for an extended period before timing out.
• Other projects in the same organization suddenly start failing even though they use the default medium class.

Diagnostic Table

Observation	Likely Cause	Immediate Check
"Insufficient Credits" banner	Monthly credit quota exhausted	Go to Organization Settings > Billing and view remaining credits.
"Unsupported resource class" error	Requested class not enabled for the plan	Review resource_class in the job definition.
Jobs queue for long time then fail	Credit exhaustion in the middle of the month	Check credit usage trend via the Billing API or UI.
All projects fail after a single heavy job	Organization-level credit cap exceeded	Audit the heavy job’s credit consumption (minutes × class rate).

Step‑by‑Step Checks

1. Verify Current Credit Balance
   • Navigate to https://app.circleci.com/settings/organization/{org-id}/billing (replace {org-id} with your organization key).
   • Look for the Remaining Credits field. If it is 0, the account has reached its limit.
   • Note: Free tiers provide 500 credits per month; paid plans scale up to 2,000+ credits.
2. Inspect the Configuration
   • Open .circleci/config.yml in the repository.
   • Locate the job that failed and confirm the resource_class value.

     jobs:
       build:
         docker:
           - image: cimg/node:20.10.0
         resource_class: large  # Possible values: medium, mediumplus, large
         steps:
           - checkout
           - run: npm install
           - run: npm test
     

   • If the class is large or mediumplus, ensure your plan supports it. The free plan only allows medium.
3. Check Job Logs for Credit‑Related Messages
   • Open the job page in the CircleCI UI.
   • Search the logs for Credit limit reached or Resource class not available.
   • These strings confirm the exact failure point.
4. Review Organization‑level Overrides
   • In the organization settings, look for Resource Class Restrictions or Credit Quota overrides.
   • Projects can be forced to a lower class if the organization has set a hard cap.
5. Measure Credit Consumption of the Failing Job
   • Each resource class consumes credits at a different rate:
     • medium: 1 credit per minute
     • mediumplus: 1.5 credits per minute
     • large: 2 credits per minute
   • Estimate the job’s runtime in minutes and multiply by the class rate to see how many credits it would consume.

Fixes Tied to Findings

• Credit Exhaustion Detected
  • Upgrade the plan: Contact sales to increase monthly credits or move to a paid plan.
  • Reduce job duration: Add caching, parallelism, or split the job into smaller steps.
  • Lower the resource class: Change resource_class to medium in config.yml and commit.
  • Schedule heavy jobs during off‑peak months or stagger them across multiple projects.
• Unsupported Resource Class Detected
  • Replace large or mediumplus with medium if the plan does not support higher tiers.
  • If you need a higher class, upgrade the plan or request a temporary allowance from CircleCI support.
  • Remember that changing resource_class requires a new commit or a manual trigger to take effect.
• Organization Override Conflict
  • Ask an organization admin to lift or adjust the resource_class restriction.
  • Alternatively, move the project to a different organization with higher limits.
• Credit Depletion from a Single Heavy Job
  • Split the heavy job into multiple smaller jobs that run sequentially.
  • Use parallelism wisely: increasing parallelism can actually reduce total credit usage if the job finishes faster.
  • Consider using a self‑hosted runner for that job; self‑hosted runners do not consume CircleCI credits.

Escalation Criteria

1. If you are on a paid plan and still hit the credit limit, contact CircleCI support to verify that the billing data is correct.
2. If the error persists after adjusting resource_class and ensuring the plan supports it, open a support ticket with the exact log snippet.
3. For organizations where multiple projects are affected, schedule a meeting with the org admin to review credit allocation and consider a plan upgrade.

Practical Verification

• After applying a fix, trigger a new workflow manually: circleci trigger -w workflow_name -r main from the CLI.
• Verify the job starts within 30 seconds and that the UI no longer shows the credit banner.
• Check the billing page again to ensure the remaining credits reflect the new usage.

Limitations and Caveats

• Credit calculations are approximate; actual consumption can vary slightly due to overhead.
• Changing resource_class mid‑pipeline requires a new commit; you cannot alter it in a running job.
• Upgrading the plan does not retroactively increase credits for the current month; you must wait until the next billing cycle.
• Self‑hosted runners bypass credit limits but introduce infrastructure maintenance overhead.

Conclusion

By systematically checking the credit balance, validating the resource class, and understanding how each job consumes credits, you can quickly pinpoint whether a failure is due to budget exhaustion or an unsupported configuration. Apply the appropriate fix—whether that’s adjusting the class, optimizing the job, or upgrading the plan—and monitor the billing dashboard to avoid future surprises.