{"record":{"id":"3d2add97d68e7dc7","repo":"gatsbyjs/gatsby","slug":"process-env-gatsby-cpu-count-is-set-to-logical-co","errorCode":null,"errorMessage":"process.env.GATSBY_CPU_COUNT is set to 'logical_cores' but there was a problem finding the number of logical cores","messagePattern":"process\\.env\\.GATSBY_CPU_COUNT is set to 'logical_cores' but there was a problem finding the number of logical cores","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"packages/gatsby-core-utils/src/cpu-core-count.ts","lineNumber":33,"sourceCode":"      // or default to 1 if we can't detect\n      return coreCount\n    }\n\n    if (typeof process.env.GATSBY_CPU_COUNT !== `undefined`) {\n      const coreCountArg =\n        Number(process.env.GATSBY_CPU_COUNT) || process.env.GATSBY_CPU_COUNT\n\n      switch (typeof coreCountArg) {\n        case `string`:\n          // Leave at Default CPU count if coreCountArg === `physical_cores`\n\n          // CPU count === logical CPU count\n          // throw error if we have a problem counting logical cores\n          if (coreCountArg === `logical_cores`) {\n            coreCount = require(`os`).cpus().length\n\n            if (typeof coreCount !== `number`) {\n              throw new Error(\n                `process.env.GATSBY_CPU_COUNT is set to 'logical_cores' but there was a problem finding the number of logical cores`\n              )\n            }\n          }\n          break\n\n        case `number`:\n          // CPU count === passed in count\n          coreCount = coreCountArg\n          break\n\n        default:\n          break\n      }\n    }\n\n    return coreCount\n  } catch (err) {","sourceCodeStart":15,"sourceCodeEnd":51,"githubUrl":"https://github.com/gatsbyjs/gatsby/blob/8b06340921ffdf23125a365b9c9923690cb62ce6/packages/gatsby-core-utils/src/cpu-core-count.ts#L15-L51","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Unset GATSBY_CPU_COUNT to fall back to physical-core detection (the default branch).","Set GATSBY_CPU_COUNT to an explicit integer (e.g. 2) to bypass os.cpus() entirely.","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."],"exampleFix":"# before\nexport GATSBY_CPU_COUNT=logical_cores\n# after (explicit, avoids os.cpus())\nexport GATSBY_CPU_COUNT=4","handlingStrategy":"validation","validationCode":"if (process.env.GATSBY_CPU_COUNT === 'logical_cores') {\n  const cpus = require('os').cpus()\n  if (!Array.isArray(cpus) || typeof cpus.length !== 'number') {\n    delete process.env.GATSBY_CPU_COUNT // fall back to physical cores\n  }\n}","typeGuard":"const hasLogicalCpuCount = (): boolean => {\n  const cpus = require('os').cpus()\n  return Array.isArray(cpus) && typeof cpus.length === 'number'\n}","tryCatchPattern":null,"preventionTips":["Prefer an explicit integer GATSBY_CPU_COUNT in containers.","Verify `node -e \"console.log(require('os').cpus().length)\"` returns a number before using logical_cores.","Use a standard Node base image in CI."],"tags":["cpu-cores","environment-variable","gatsby-core-utils","container"],"backgroundTag":null,"analyzedSha":"8b06340921ffdf23125a365b9c9923690cb62ce6","analyzedAt":"2026-08-13T02:36:21.405Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}