{"record":{"id":"45f57c45d749e596","repo":"actualbudget/actual","slug":"actual-app-api-requires-a-node-version-minimumn","errorCode":null,"errorMessage":"@actual-app/api requires a node version ${minimumNodeVersion}. Found that you are using: ${nodeVersion}. Please upgrade to a higher version","messagePattern":"@actual-app/api requires a node version (.+?)\\. Found that you are using: (.+?)\\. Please upgrade to a higher version","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/api/validateNodeVersion.ts","lineNumber":10,"sourceCode":"import { satisfies } from 'compare-versions';\n\nimport * as packageJson from './package.json';\n\nexport function validateNodeVersion(): void {\n  const nodeVersion = process.versions.node;\n  const minimumNodeVersion = packageJson.engines.node;\n\n  if (!satisfies(nodeVersion, minimumNodeVersion)) {\n    throw new Error(\n      `@actual-app/api requires a node version ${minimumNodeVersion}. Found that you are using: ${nodeVersion}. Please upgrade to a higher version`,\n    );\n  }\n}\n","sourceCodeStart":1,"sourceCodeEnd":15,"githubUrl":"https://github.com/actualbudget/actual/blob/d4334cb6e6123f4d3bcea1ad6166608884c7e658/packages/api/validateNodeVersion.ts#L1-L15","documentation":"@actual-app/api checks process.versions.node against the engines.node range from its package.json at init time. If the running Node version does not satisfy that range, init refuses to start. This prevents subtle breakage from unsupported Node runtimes.","triggerScenarios":"Running a script/app that calls api.init() on a Node version outside the supported range (e.g. Node 18/20 when engines requires >=22, or very new unreleased Node).","commonSituations":"CI runners pinned to an older Node; Docker images with stale base images; deploy servers with a system Node older than development; using nvm without selecting the right version.","solutions":["Upgrade Node to a version matching the engines range shown in the message (e.g. nvm install 22 && nvm use 22).","Update CI (GitHub Actions setup-node node-version) and Dockerfile base image to a supported Node.","If truly necessary, bypass via api.init with the version check removed — not recommended; instead match the required Node."],"exampleFix":"// before (CI workflow)\n- uses: actions/setup-node@v4\n  with:\n    node-version: 18\n// after\n- uses: actions/setup-node@v4\n  with:\n    node-version: 22","handlingStrategy":"validation","validationCode":"import { satisfies } from 'semver';\nimport packageJson from '@actual-app/api/package.json';\nif (!satisfies(process.versions.node, packageJson.engines.node)) {\n  throw new Error(`Upgrade Node to ${packageJson.engines.node} before using @actual-app/api`);\n}","typeGuard":"null","tryCatchPattern":"try {\n  await api.init(config);\n} catch (e) {\n  if (String(e.message).includes('requires a node version')) {\n    console.error(e.message);\n    process.exit(1); // fail fast with clear message in CI/deploys\n  }\n  throw e;\n}","preventionTips":["Pin Node in CI via actions/setup-node with the version from engines.","Use .nvmrc and run `nvm use` in shells and scripts.","Use a Node base image matching engines.node in Dockerfiles.","Add a preflight version check at script startup."],"tags":["node","environment","version-check","api"],"backgroundTag":"unsupported-node-version","analyzedSha":"d4334cb6e6123f4d3bcea1ad6166608884c7e658","analyzedAt":"2026-08-29T01:02:11.213Z","schemaVersion":2},"datasetVersion":"2026-08-29T02:17:18.158Z"}