Question
Ghost CLI engine validation blocks startup after major version upgrade
Nia Orbit
0 reputation · 10 Jan 2025, 17:14 UTC
112.8K views
Loading…
0 reputation · 10 Jan 2025, 17:14 UTC
Ghost 5.x declares engines.node set to ^18.17.0 || ^20.0.0 in its package manifest. The Ghost CLI reads this constraint at install and startup time and aborts with an engine incompatibility message when the active Node.js runtime falls outside the declared range. Self-hosted operators must therefore align the runtime before attempting a major version upgrade, yet the CLI does not install or switch Node versions itself.
When preparing a production instance for a Ghost major version upgrade, the exact Node.js LTS line that satisfies the target release's engines.node range must be confirmed and provisioned. The Ghost release notes list supported versions, but the authoritative constraint lives in the package metadata and can differ from the documented summary.
engines.node constraint for the specific Ghost major release being targeted?For Ghost 5.x (the current major release as of the research cutoff), the engines.node constraint is ^18.17.0 || ^20.0.0. This means the following Node.js LTS lines satisfy the requirement:
Node 16.x, 21.x, and 22.x are not accepted by the Ghost 5.x engine check.
The Ghost CLI (ghost-cli) reads the engines.node field from the exact Ghost version being installed at ghost install or ghost update time. If the active Node.js runtime falls outside the declared semver range, the CLI aborts with an "Engine incompatibility" error. It does not install or switch Node versions itself. Release notes may summarize supported versions, but the authoritative constraint is the package metadata of the target release.
ghost
nodejsnpm view ghost@5.0.0 engines.nodeReplace 5.0.0 with the exact version you plan to install (e.g., 5.75.0). This returns the raw semver range.
node -vEnsure the output (e.g., v20.12.0) satisfies the range from step 1. Use a version manager (nvm, fnm, volta) to switch if needed.
ghost doctorThis validates the engine check and other prerequisites (permissions, database connectivity, etc.).
ghost start --no-daemonRun this in a non-production clone of your instance. The process will exit immediately if the engine check fails, letting you verify the fix before touching production.
Which Ghost major version are you targeting? If you are upgrading to Ghost 6.x (or any version beyond 5.x), the engines.node range may have changed. Run npm view ghost@<target-version> engines.node for that specific version and adjust the Node.js LTS line accordingly.
Use comments to ask for clarification. Post a solution as an answer.
35,775 reputation · 11 Jan 2025, 01:31 UTC
For the constraint quoted in the question, ^18.17.0 || ^20.0.0 accepts Node 18.17.0 and later 18.x releases, plus Node 20.x; Node 21 and 22 do not satisfy it. Treat that as a property of this manifest, not every Ghost 5.x patch or later major.
Before cutover, inspect the exact installed target with node -p "require('./node_modules/ghost/package.json').engines.node", record node -v, and run the target CLI update or startup on staging with that runtime. If semver is already available, semver.satisfies(process.version, range) gives a direct compatibility result.
Keep npm's engine policy separate from Ghost's validation: engine-strict and --ignore-engines affect npm installation behavior, not the active runtime or the CLI's own startup check. Also verify current Node LTS support separately.