Upgrading Ghost from version 5 to version 6 should be straightforward, but sometimes you'll encounter dependency conflicts and Node.js version mismatches that can make the process challenging. In this comprehensive guide, I'll walk you through resolving the common "engine appears to be invalid" error and successfully upgrading your Ghost blog from v5.82.4 to v6, including all the pitfalls you might encounter along the way.

This guide is based on a real-world upgrade scenario on Ubuntu 22.04.3 LTS, where we encountered and resolved multiple issues including Node.js version conflicts, npm dependency errors, and missing package.json files.

The Initial Problem

When attempting to update Ghost v5.82.4 to the latest v5 version (5.130.5), you might encounter an error like this:

Warning Resolution field "moment@2.24.0" is incompatible with requested version "moment@^2.29.4"
Warning Resolution field "moment@2.24.0" is incompatible with requested version "moment@^2.27.0"
...
Error mocha@11.7.1: The engine "node" is incompatible with this module. Expected version "^18.18.0 || ^20.9.0 || >=21.1.0". Got "18.17.1"
Error Found incompatible module.

This error occurs because:

  1. Your Node.js version is outdated for the Ghost version you're trying to install
  2. There are dependency conflicts between various npm packages
  3. The installed npm modules were built with a different Node.js version

Prerequisites

Before starting, ensure you have:

  • Root or sudo access to your server
  • A working Ghost installation (v5.x)
  • Basic command line knowledge
  • At least 1GB of free disk space

Step-by-Step Solution

Step 1: Diagnose Your Current Setup

First, let's check your current environment:

bash

# Check your Ghost version
ghost version

# Check Node.js version
node --version

# Check npm version
npm --version

# Check Ghost CLI version
ghost --version

# List Ghost installations
ghost ls

# Check your Ghost installation directory structure
ls -la /var/www/ghost/

Step 2: Backup Everything

Before making any changes, create comprehensive backups:

bash

# Navigate to your Ghost directory
cd /var/www/ghost

# Stop Ghost
ghost stop

# Create a full file backup
sudo tar -czf ~/ghost-backup-$(date +%Y%m%d-%H%M%S).tar.gz .

# Backup the database
ghost backup-db

# Export content from Ghost Admin (do this from the web interface)
# Go to: https://yourdomain.com/ghost/
# Navigate to: Settings → Labs → Export your content

Step 3: Fix Node.js Version Mismatch

The "engine appears to be invalid" error typically means your Node.js version is too old. Let's update it:

bash

# Update to the latest Node.js v18 (for Ghost v5)
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get update
sudo apt-get install -y nodejs

# Verify the update (should show v18.20.x or higher)
node --version

Step 4: Resolve npm Dependency Conflicts

Ghost's file structure uses versioned directories with a symlink. Understanding this is crucial:

bash

# Ghost root directory
/var/www/ghost/
    ├── current -> /var/www/ghost/versions/5.82.4  (symlink)
    ├── content/  (your data)
    └── versions/
        └── 5.82.4/  (actual Ghost installation)

To fix dependency issues:

bash

# Navigate to the actual Ghost installation
cd /var/www/ghost/current

# Clean everything
rm -rf node_modules
rm -f package-lock.json
npm cache clean --force

# Reinstall dependencies with force flag
npm install --production --force

Note: If you get "Could not read package.json" error, you're in the wrong directory. Always run npm commands from /var/www/ghost/current, not from /var/www/ghost.

Step 5: Update Ghost CLI

Always ensure you have the latest Ghost CLI before updating:

bash

# Update Ghost CLI globally
sudo npm install -g ghost-cli@latest

# Verify the update
ghost --version

Step 6: Update to Latest Ghost v5

Now update to the latest v5 version:

bash

# Navigate to Ghost root
cd /var/www/ghost

# Start Ghost if stopped
ghost start

# Run diagnostics
ghost doctor

# Update to latest v5
ghost update v5

If you encounter errors, try:

bash

ghost update v5 --force

Step 7: Prepare for Ghost v6

Ghost v6 requires Node.js v20 or v22. Let's upgrade:

bash

# Install Node.js v22 (recommended for Ghost v6)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get update
sudo apt-get install -y nodejs

# Verify the update
node --version  # Should show v22.x.x

# Update Ghost CLI again (important!)
sudo npm install -g ghost-cli@latest

Step 8: Backup Before Major Version Upgrade

When running ghost backup, you'll need a staff access token:

  1. Go to your Ghost admin: https://yourdomain.com/ghost/
  2. Navigate to Settings → Staff → Your User
  3. Scroll to "Staff Access Tokens" section
  4. Click "Generate new token"
  5. Copy and save the token immediately

Then run:

bash

ghost backup
# Enter your staff access token when prompted

Step 9: Upgrade to Ghost v6

Finally, perform the major version upgrade:

bash

# Ensure you're in the Ghost directory
cd /var/www/ghost

# Run the upgrade
ghost update v6

Step 10: Post-Upgrade Verification

After the upgrade completes:

bash

# Verify Ghost version
ghost version  # Should show 6.x.x

# Check status
ghost ls

# Run diagnostics
ghost doctor

# Check logs for any errors
ghost log

# Test your site
curl -I http://localhost:2368

Visit your website and admin panel to ensure everything works correctly.

Common Issues and Solutions

Issue 1: Permission Errors

bash

# Fix with sudo
sudo ghost update v6

# Or fix ownership
sudo chown -R ghost-mgr:ghost-mgr /var/www/ghost

Issue 2: Dependency Conflicts

bash

# Use force flag
ghost update --force

# Or clean install dependencies
cd /var/www/ghost/current
rm -rf node_modules
npm install --production --force

Issue 3: Update Fails

bash

# Rollback to previous version
ghost rollback

# Check logs for specific errors
tail -f /var/www/ghost/content/logs/ghost.log

Issue 4: Theme Compatibility

After upgrading to v6, your theme might need updates. Check:

  • Ghost admin → Settings → Design
  • Look for any theme warnings
  • Update or replace incompatible themes

Key Takeaways

  1. Always backup before updating - Use both file backups and database exports
  2. Node.js version matters - Ghost v5 needs Node.js v18.18+, Ghost v6 needs v20+
  3. Understand Ghost's directory structure - Run Ghost commands from /var/www/ghost, npm commands from /var/www/ghost/current
  4. Update Ghost CLI first - Always update the CLI before updating Ghost itself
  5. Use force flags when needed - Both npm install --force and ghost update --force can resolve stubborn issues
  6. Document your process - Keep notes of what worked for future reference

Conclusion

Upgrading Ghost from v5 to v6 can seem daunting when you encounter errors, but with the right approach and understanding of the underlying issues, it's entirely manageable. The key is to:

  • Address Node.js version requirements first
  • Clean up dependency conflicts
  • Follow the upgrade path sequentially (v5 → latest v5 → v6)
  • Always maintain backups

By following this guide, you should be able to successfully upgrade your Ghost installation while avoiding common pitfalls. Remember that Ghost v6 brings significant improvements in performance and features, making the upgrade effort worthwhile.

If you encounter issues not covered in this guide, the Ghost community forum and official documentation are excellent resources for additional help.

Share this post