Troubleshooting

This troubleshooting guide lists common errors faced with installing, upgrading and using Ghost.

As well as this guide, more specific troubleshooting guides can be found at:
Importer Troubleshooting
Admin Client Troubleshooting
Server Troubleshooting

If you're still stuck or need more help after reviewing this guide, please head on over and join our forum, where you'll find a help category.


General

ghost start or ghost restart error

If you get an error when trying to do either ghost start or ghost restart, the first thing to do is to try using ghost run first to check that Ghost can start successfully.

The start and restart commands are both talking to your process manager (e.g. systemd) and so can hide any underlying errors from Ghost.

You can also try looking at your Ghost log files that live in /content/logs/. After this you can be sure there's nothing wrong with Ghost itself, and the problem is with the process manager.

Ghost Admin not loading

If you've added CloudFlare to your site, you may find that Ghost Admin doesn't load after updates, if you open dev tools you will likely find weird errors like TypeError: n.item is not a function or Uncaught SyntaxError: Unexpected string in the JavaScript console.

It is recommended that you add a page rule which turns off RocketLoader, mirage2 and autominify for the path /ghost*, so these features don't affect the Ghost admin panel.

If you're on Ghost(Pro) both nginx and CloudFlare have been configured such that these issues do not occur.

NET::ERR_CERT_DATE_INVALID

If you get an Error NET::ERR_CERT_DATE_INVALID on your site, this is due to a bug in Ghost-CLI < 1.2.0 to do with SSL renewal. The certificates have been renewed but nginx needs restarting to complete the process.

To fix this: Run:


sudo nginx -s reload

or sudo systemctl restart nginx or however you prefer to restart nginx.

This is fixed in Ghost-CLI 1.3.0. Please upgrade.

ERROR: Your content path does not exist!

This happens when Ghost is unable to read or write to the content path. Check that the path is correct, exists, and that the user you're running Ghost with has the permissions to read and write to that folder. This error will also occur if any of the expected subfolders: 'adapters', 'data', 'images' and 'themes' are missing or not writable. Read more about configuration files in Ghost here.

ERROR: URL in config must be provided with protocol

Please read our Configuring Ghost guide again.

ERROR: Unable to open sqlite3 database file for read/write (exit code 236)

This error indicates that the sqlite3 database file is either not readable or not writable by the user running Ghost. Normally this file exists in content/data/ but this path can be configured in your config file. Ensure that the path in the config is correct and that the path is both readable and writable by the user running Ghost. Read more about configuration files in Ghost here.

Error: connect ECONNREFUSED 127.0.0.1:3306

If you get an ECONNREFUSED error, which refers to port 3306, this means that Ghost wasn't able to connect to your MySQL server.

Please make sure that the server is running, e.g. sudo service mysql start. You can test if the server is running by typing mysql in the command line.

If you get this error during a ghost install you will need to rerun the setup phase, using ghost setup.

MySQL throws ER_WRONG_FIELD_WITH_GROUP

...which is not functionally dependent on columns in GROUP BY clause; this is incompatible with sql_mode=only_full_group_by...

You MySQL database is misconfigured. Please open your my.cnf (sudo find / -name my.cnf) and remove only_full_group_by from sql_mode.

Ghost crashes when importing

If you're importing a large amount of data, ghost might crash. If your error
has something along the lines of FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory, you need to run ghost with more memory allocated to it.

Assuming you installed via the cli, cd into your installation directory and run node --max_old_space_size=4096 --optimize_for_size --max_executable_size=4096 --stack_size=4096 current/index.js. This will run ghost in the foreground and log all of the requests that are made to it. Now, import your content like normal. The import should complete, assuming you have enough RAM. Once the import completes, terminate the ghost instance (ctrl+c in the terminal window) and start ghost normally (ghost start).


CLI errors

General install error

If your install fails, and you can't find a specific solution you can try ghost uninstall and ghost install again.

General update error

✖ Running database migrations

If your update fails whilst trying to upgrade Ghost, you can always try ghost update --rollback to revert to an earlier version.

task.execute is not a function

If you are running into this error, please first ensure you rollback the version with ghost update --rollback and double check if your blog is back. We have announced that you should upgrade your CLI version, so please do and then try again.

Fix root user

When you installed Ghost with the DigitalOcean One-Click install you probably set up your Ghost installation as a root user. With Ghost-CLI 1.5.0, it will not be allowed to run Ghost commands as root. Therefore you will need to migrate your current installation to a new linux user.

Run the following steps as root user to fix it:

Add a new user:

adduser <user>

Add user to sudo group:

usermod -aG sudo <user>

Now create a new instance file and move to new user location:

mkdir -p /home/<user>/.ghost/

chown <user>:<user> /home/<user>/.ghost

mv /root/.ghost/config /home/<user>/.ghost/config

chown <user>:<user> /home/<user>/.ghost/config

Next, change into your ghost installation directory (/var/www/ghost/ is default in the DigitOcean One-Click installs) to change the ownership of your installation files:

cd /var/www/ghost

And then execute this command (might take a while):

find . -group root -user root -exec chown <user>:<user> {} \;

Last step, Login as new user:

su - <user>

You can check ghost ls now to see if your installation is still up and running!

Yarn errors while running ghost install or ghost update

RangeError: Array buffer allocation failed

This looks like a memory problem. Please ensure you have enough free memory or configure swap.

Error occurred running command: 'yarn install --no-emoji --no-progress'

That looks like an out of memory exception. Please ensure you have enough free memory or configure swap.

SQLite3 install failure

Ghost >= 1.3.0 does no longer depend on knex-migrator, which has installed the binary dependency SQLite3. And that's why you should no longer run into SQLite3 problems with the CLI when switching node versions.

If you are running into this problem, please ensure you upgrade to the latest CLI version.

SQlite3 installation in Ghost itself

If you have switched your node version and you are still running into problems, you have to fix the SQlite3 installation in your active Ghost blog. Continue reading here.

The CLI says Ghost was started, but ghost ls shows it's stopped

If you hit a problem like this, please run: sudo systemctl status service-name.

Note

You can find your service name in cd ghost-installation-folder; ls -la system/files.

Error with MySQL: ER_NOT_SUPPORTED_AUTH_MODE

This error is most likely caused by installing MySQL with a blank root password. Ghost-CLI/Ghost are unable to connect to the database when it is in blank root password mode.

To add a password for your root user :

# This connects to mysql
mysql -u root
# In the mysql prompt, run:
use mysql;
update user set authentication_string=password(''), plugin='mysql_native_password' where user='root';

Alternatively, you can login to mysql, create your own database, user and password, then provide these in your config.x.json file.

After running the above commands, Ghost-CLI should start to work again. Run ghost setup to continue to the setup process, or ghost setup migrate to run just the database migrations.

status=203/EXEC

Ensure you have node.js installed globally (accessible from /usr/local/node).
Ensure you have installed Ghost within e.g. /var/www. A Ghost installation within e.g. /root can cause trouble, please reinstall in e.g. /var/www/ghost.

Error: EACCES: permission denied

This error means you are running into permission problems with the files and folders in your Ghost install not belonging to the correct user.

If you get an EACCES: permission denied error followed by the path to your content folder/var/www/ghost/content/... this is likely because you added some files there manually and did not change them to be owned by the ghost user. In a standard install the ghost user must own the /content/ directory and everything beneath it.

This problem can be fixed by running sudo chown -R ghost:ghost content from inside your Ghost install.

If you are not using the standard install with a ghost user, you must still change the content/ directory to be owned by whichever user runs Ghost.

If you are logging in via ssh and have just created your user. Logging out and back in again can help.

If your EACESS error was for a different file or folder, pay attention to the method (E.g. open, or mkdir) in the error and the path. Open means no read permission, mkdir means no write permission. The user used to run ghost x commands will need read and write access to the files inside your Ghost install.

EACCES: permission denied, unlink '/var/www/ghost/versions/1.19.0/.eslintrc.json'

When updating Ghost and you are running into this error message, it's most likely a permission problem. Check, if the /versions directory has the same owner and permissions as the other folders (except /content).

This issue can be fixed by running sudo chown -R <user>:<user> versions from within the Ghost installation directory and try ghost update again.

Job for nginx.service failed because the control process exited with error code. See "systemctl status nginx.service" and "journalctl -xe" for details.

This error usually happens, if you setup nginx via the CLI and it tries to generate a SSL certificate, but fails due to e.g. renew problems. The ssl parameters are anyway added to NGINX and NGINX fails to restart. Please navigate to your Ghost installation folder and open the NGINX config file in system/files/your-domain.conf and remove the ssl certificate. Afterwards you can start Ghost with ghost start. You can always re-setup ssl with ghost setup ssl. Don't forget to restart your instance afterwards.

Bad Gateway

If you browser shows 502 Bad Gateway, then your Ghost blog is not running.
Please navigate to your Ghost installation folder and run ghost ls to check wether your instance is running.
If it's stopped, please run ghost start. You can also run ghost log -f to watch the Ghost log.

Connection refused

If you see a Connection Refused error in the browser, this can have multiple reasons.

NGINX was removed

If you install NGINX and then remove it with again, the CLI can't detect that NGINX is not installed anymore. This is caused by caching issue and the way the CLI detects that NGINX is installed (with dpkg -l | grep nginx) . Please reinstall NGINX by running sudo apt-get install nginx.

NGINX is not running

Please run sudo service nginx status to verify if NGINX is running.
If it shows inactive, please execute sudo service nginx start.

Unit nginx.service is masked

If you are getting this error, then sytemd masked the nginx to prevent it from starting. You have to execute sudo systemctl unmask nginx.service.

SSL problems

Error getting validation data / Verify error:Invalid response from <url>

One of the reasons of this error is that your domain is bound to a different server ip. Please double check your domain provider.

✖ Migrating SSL certs

In 1.3.0 we've added a migration to fix underlying ssl certificate problems.
If this step fails for you, this might have the following reasons:

  • ensure you are logged in as your administrative user, which you have setup here
  • double check the permissions in your blog folder (ls -la /var/www/ghost)
    • all folders and files should be owned by your administrative user, which you have setup here
    • the only exception is the content folder, which should be owned by ghost
    • if your permissions are wrong, please follow these steps
  • the domain certificate folder should contain the file fullchain.cer (ls -la /etc/letsencrypt/your-domain)
    • if this file is missing, please remove the old ssl certificates and regenerate them

SSL renew

too many certificates already issued for exact set of domains

Letsencrypt has a rate limit, see https://letsencrypt.org/docs/rate-limits/.
You can generate 5 certificates per week per domain. The CLI auto renews your ssl script every month as long as you prompt yes on Ghost installation.

If no, you can run ghost setup ssl-renew.

Certificate not due for renewal yet, skipping

Same as above.

Error installing Ghost behind a proxy server

If you try to install Ghost-CLI from behind a proxy server you may encounter the following error:

$ghost install
 ✔ Checking for latest Ghost version
 ✔ Running system checks
 ✔ Setting up install directory
 ❯ Downloading and installing Ghost v1.0.0-beta.1
   ✔ Getting download information
   ✖ Downloading
     → tunneling socket could not be established, cause=connect EINVAL 0.0.0.80:80 - Local (0.0.0.0:0)
     Installing dependencies
   Moving files
An error occurred.
Message: 'tunneling socket could not be established, cause=connect EINVAL 0.0.0.80:80 - Local (0.0.0.0:0)'

This can be resolved by adding a protocol to the proxy server url.

Example:

export http_proxy=http://proxy-server:80
export https_proxy=http://proxy-server:80

Error: Cannot find module '/usr/lib/node_modules/ghost-cli/node_modules/sqlite3/lib/binding/node-v48-linux-x64/node_sqlite3.node'

Sqlite3 is a binary dependency that comes with precompiled binaries and downloads the right one for your system on install. If you change the environment, it will look for a different binary, which wasn't downloaded. This error is caused by changing node versions after installing ghost-cli.

Please run:
npm un -g ghost-cli && npm i -g ghost-cli

The current directory is not writable

✖ Running system checks
An error occurred.
Message: 'The current directory is not writable.
Please fix your directory permissions.'

Please ensure that the folder you are trying to install Ghost in is owned by your ubuntu user.
sudo chown user:user your-installation-folder should help.

Update problems

If you upgraded with Ghost-CLI and something went wrong, you can always do

ghost update --rollback

To revert to the previous version, and get a working install again.

To attempt the upgrade again, run

ghost update --force

SQLite3 errors

The most complicated part of a Ghost install is getting the node-sqlite3 module, which requires a binary. Binaries are difficult because they have to be compiled for your particular operating system and environment, and compiling in turn requires various tools to be available on the computer. Most people won't have the right setup, so to make this MUCH easier, the SQLite3 package comes with pre-built binaries for the most common architectures.

This means, that it attempts to download a file from a server during the install. This will only work if you have a common architecture and an internet connection that permits the download. If you are using a less popular linux or unix flavor, you may find that SQLite3 will give you a 404 error:

ERROR: not found, falling back to source compile

It will then attempt to compile an SQLite3 binary for your architecture from the source. If this doesn't work, it'll then say:

ERROR: Build failed

You may also see errors like npm ERR! sh "-c" "node build.js" failed with 1

If you receive this sort of error, the first thing to check is that you don't have a firewall or other issue with your connection that may be blocking the binary download. Especially if you're using a pretty standard Windows, mac or linux architecture, this is more likely to be the problem.

If you're using ARM or some other "slightly-off-the-beaten-track" architecture, you're going to need to get down and dirty compiling your own binary. This means having all of the requirements for node-gyp. Once you've got those installed, you can try it out by running npm install sqlite3 --build-from-source.

If it won't build you're probably missing one of the python or gcc dependencies, on linux try running sudo npm install -g node-gyp, sudo apt-get install build-essential and sudo apt-get install python-software-properties python g++ make before retrying the build from source.

To get more information about what's failing, run npm install sqlite3 --loglevel=info. You should then find a more detailed messages explaining:


  1. Why it is falling back to build in the first place usually a "Not found" message, look for the lines like:

    info using node-pre-gyp@0.6.7
    node-pre-gyp info using node@4.2.4 | linux | arm
    node-pre-gyp info check checked for "/home/ghost/ghost/node_modules/sqlite3/lib/binding/node-v46-linux-arm/node_sqlite3.node" (not found)


  2. Why the build itself is failing, look for the line like gyp ERR! build error, the issue usually appears just before this.


If you need more help, put the full output from npm install sqlite3 --loglevel=info into a gist and post it in the help category on the Ghost forum.

Ghost for production usage

We highly recommend switching to MySQL for your production blog.

If you want to switch your blog from using SQlite3 to MySQL, please follow this guide.

  • Ensure MySQL is installed
  • Update config to MySQL using ghost config --db mysql --dbhost <host> --dbuser <user> --dbpass <pass> --dbname <name>
  • (optional) Run ghost setup mysql if you want Ghost to create a special MySQL user
  • Run ghost setup migrate to initialise the new database

Node issues

ERROR: /usr/local/bin doesn't appear in my $PATH

You can add it by doing the following:


  • In your terminal window type cd ~, this will take you to your home directory

  • Now type ls -al to show all the files and folders in this directory, including hidden ones

  • You should see a file called .profile or .bash_profile if not type touch .bash_profile to create a file

  • Next, type open -a Textedit .bash_profile to open the file with Textedit.

  • Add export PATH=$PATH:/usr/local/bin/ at the end of the file and save it

  • This new setting will get loaded when a new terminal starts, so open a new terminal tab or window and type echo $PATH to see that '/usr/local/bin/' is now present.
    Ghost will not run with a Node.js version older than 0.10.40.


Using nvm

  • Ensure that nvm is not installed in the root folder. i.e. ensure you don't have a /root/.nvm folder. If you do, you'll need to uninstall nvm, and reinstall it using a non-root user.

  • If possible, set your nvm default version to be the one you will use for Ghost, before installing the CLI. This is especially important when using sqlite3.

  • If your default is different, you will need to remember to switch every time you start a new session, before running any ghost commands, otherwise you will get sqlite3 related errors.

  • When running ghost commands, make sure that the paths for which ghost and npm root -g are the same - these will be different if you changed node version between installing and using ghost-cli. You may need to switch node version using nvm, to match the one given by which ghost.

E.g. on a machine with nvm configured correctly, you should see something like:

which ghost -> /Users/[username]/.nvm/versions/node/[node version]/bin/ghost
npm root -g -> /Users/[username]/.nvm/versions/node/[node version]/lib/node_modules

If these 2 paths are not in the same [node version], it means you've installed ghost-cli in a different environment than the active node environment. This is common since you can have many node versions installed via nvm, each with its own global node_modules. ghost-cli needs to be installed AND run in the same environment to access specific node modules binary (like sqlite3) can be found.

You have 2 options:

  1. You can npm install ghost-cli -g in the current environment (to get the right sqlite3 node module into the environment) and go through ghost setup process again or
  2. If you remember which nvm node environment you've installed ghost-cli under, run nvm use <node version> and run which ghost to see if it's there and setup ghost instance in that environment.

Image upload issues

Image uploads can be affected by two known incompatibility issues. The CLI sets the max upload size to 50MB by default.

If you need more, you will need to increase the limit by editing your nginx config file, and setting the limit to something else.


  • Log into your server

  • Navigate to your Ghost installation folder with cd /var/www/ghost.

  • Type: nano system/files/your-domain.conf to open your NGINX config file.

  • Edit client_max_body_size {VALUE}M;

  • Finally, press ctrl + x to exit. Nano will ask you if you want to save, type y for yes, and press enter to save the file.

  • Restart NGINX by running sudo service nginx restart.

Troubleshooting