CircleCI "resource_class is invalid" - Fix Resource Classes

By Kaveh Alemi·Latchkey

The resource_class you set is not valid for this executor or not available on your plan. CircleCI rejects the job because it cannot allocate the machine size you requested.

What this error means

The job fails to start with a message that the resource class is invalid or unavailable. It is deterministic - the same config requests the same unavailable size every run.

resource_class "2xlarge+" is not available for your plan
# or
resource_class "large" is not valid for the macos executor

Common causes

Unknown or misspelled class name

Valid Docker/Linux classes are small, medium, medium+, large, xlarge, 2xlarge, 2xlarge+. A typo or an invented name is rejected.

Class not available on your plan

Larger classes and some arm/GPU classes require a paid plan or explicit access. On a free plan they fail to allocate.

Class does not match the executor type

Each executor (docker, machine, macos, windows) has its own set of valid resource classes. A Docker class name under a macOS executor is invalid.

How to fix it

Use a valid class for the executor

jobs:
  build:
    docker:
      - image: cimg/node:20.11
    resource_class: large   # small | medium | medium+ | large | xlarge | 2xlarge

  ios-build:
    macos:
      xcode: 15.3.0
    resource_class: macos.m1.medium.gen1

Match the class to your plan

1. Check which classes your plan allows in Plan → Usage.
2. Step down to an available class, or enable larger classes on a paid plan.
3. For arm/GPU classes, confirm access is enabled for the org.

How to prevent it

• Pick resource classes from the documented set for each executor.
• Confirm plan availability before pinning a large class.
• Centralize resource_class in a reusable executor to avoid drift.

Frequently asked questions

Related guides

References

• GitHub Actions documentation