gatsbyjs/gatsby · warning

process.env.GATSBY_CPU_COUNT is set to 'logical_cores' but t

Error message

process.env.GATSBY_CPU_COUNT is set to 'logical_cores' but there was a problem finding the number of logical cores

What it means

Thrown by cpuCoreCount when the env var GATSBY_CPU_COUNT is the literal string 'logical_cores' but `require('os').cpus().length` did not yield a number. In normal Node environments os.cpus().length is always a number, so this fires only in constrained runtimes where the cpus() call returns an empty/non-numeric result.

Source

Thrown at packages/gatsby-core-utils/src/cpu-core-count.ts:33

      // or default to 1 if we can't detect
      return coreCount
    }

    if (typeof process.env.GATSBY_CPU_COUNT !== `undefined`) {
      const coreCountArg =
        Number(process.env.GATSBY_CPU_COUNT) || process.env.GATSBY_CPU_COUNT

      switch (typeof coreCountArg) {
        case `string`:
          // Leave at Default CPU count if coreCountArg === `physical_cores`

          // CPU count === logical CPU count
          // throw error if we have a problem counting logical cores
          if (coreCountArg === `logical_cores`) {
            coreCount = require(`os`).cpus().length

            if (typeof coreCount !== `number`) {
              throw new Error(
                `process.env.GATSBY_CPU_COUNT is set to 'logical_cores' but there was a problem finding the number of logical cores`
              )
            }
          }
          break

        case `number`:
          // CPU count === passed in count
          coreCount = coreCountArg
          break

        default:
          break
      }
    }

    return coreCount
  } catch (err) {

View on GitHub (pinned to 8b06340921)

Solutions

1. Unset GATSBY_CPU_COUNT to fall back to physical-core detection (the default branch).
2. Set GATSBY_CPU_COUNT to an explicit integer (e.g. 2) to bypass os.cpus() entirely.
3. If you need logical-core scaling, ensure the runtime exposes CPU info: use a standard Node image and verify `node -e "console.log(require('os').cpus().length)"` returns a number.

Example fix

# before
export GATSBY_CPU_COUNT=logical_cores
# after (explicit, avoids os.cpus())
export GATSBY_CPU_COUNT=4

if (process.env.GATSBY_CPU_COUNT === 'logical_cores') {
  const cpus = require('os').cpus()
  if (!Array.isArray(cpus) || typeof cpus.length !== 'number') {
    delete process.env.GATSBY_CPU_COUNT // fall back to physical cores
  }
}

const hasLogicalCpuCount = (): boolean => {
  const cpus = require('os').cpus()
  return Array.isArray(cpus) && typeof cpus.length === 'number'
}

When it happens

Trigger: Setting GATSBY_CPU_COUNT=logical_cores in an environment where os.cpus() returns [] or is stubbed (some sandboxes, minimal containers, or test doubles). The guard `if (typeof coreCount !== 'number')` then trips.

Common situations: CI containers or serverless runtimes that mask CPU info; older Node versions in cgroup-limited containers where /proc/cpuinfo is hidden; setting GATSBY_CPU_COUNT=logical_cores in a jest test that mocks os; Docker images built from scratch without /sys.

Related errors

• There has been a problem counting the number of CPU cores
• You must specify either a cache or a directory
• The following page component must contain '?__contentFilePat

AI-assisted analysis of gatsbyjs/gatsby@8b06340921 (2026-08-13). Data as JSON: /api/errors/3d2add97d68e7dc7. Report an issue: GitHub.