This troubleshooting guide lists common errors faced with installing, upgrading and using Ghost.
If you're still stuck or need more help after reviewing this guide, please head on over and join our public Slack community, where you'll find a #help channel.
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.
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
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.
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
sudo systemctl restart nginx or however you prefer to restart nginx.
This is fixed in Ghost-CLI 1.3.0. Please upgrade.
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.
Please read our Configuring Ghost guide again.
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.
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
...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
sudo find / -name my.cnf) and remove
If your install fails, and you can't find a specific solution you can try
ghost uninstall and
ghost install again.
If your update fails whilst trying to upgrade Ghost, you can always try
ghost update --rollback to revert to an earlier version.
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.
This looks like a memory problem. Please ensure you have enough free memory or configure swap.
That looks like an out of memory exception. Please ensure you have enough free memory or configure swap.
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.
If you hit a problem like this, please run:
sudo systemctl status service-name.
You can find your service name in
cd ghost-installation-folder; ls -la system/files.
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
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.
Ensure you have node.js installed globally (accessible from
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.
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.
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.
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.
If you see a
Connection Refused error in the browser, this can have multiple reasons.
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.
sudo service nginx status to verify if NGINX is running.
If it shows
inactive, please execute
sudo service nginx start.
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.
One of the reasons of this error is that your domain is bound to a different server ip. Please double check your domain provider.
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)
- the domain certificate folder should contain the file
ls -la /etc/letsencrypt/your-domain)
- if this file is missing, please remove the old ssl certificates and regenerate them
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.
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.
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.
npm un -g ghost-cli && npm i -g ghost-cli
✖ 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.
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
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:
It will then attempt to compile an SQLite3 binary for your architecture from the source. If this doesn't work, it'll then say:
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:
- Why it is falling back to build in the first place usually a "Not found" message, look for the lines like:
info using firstname.lastname@example.org
node-pre-gyp info using email@example.com | 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)
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 channel on slack.
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 mysqlif you want Ghost to create a special MySQL user
ghost setup migrateto initialise the new database
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 -alto show all the files and folders in this directory, including hidden ones
- You should see a file called
.bash_profileif not type
touch .bash_profileto create a file
- Next, type
open -a Textedit .bash_profileto open the file with Textedit.
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 $PATHto see that '/usr/local/bin/' is now present.
Ghost will not run with a Node.js version older than 0.10.40.
Ensure that nvm is not installed in the root folder. i.e. ensure you don't have a
/root/.nvmfolder. 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
ghostcommands, otherwise you will get sqlite3 related errors.
When running ghost commands, make sure that the paths for
npm root -gare 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
E.g. on a machine with nvm configured correctly, you should see something like:
which ghost ->
npm root -g ->
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:
- You can
npm install ghost-cli -gin the current environment (to get the right sqlite3 node module into the environment) and go through
ghost setupprocess again or
- If you remember which nvm node environment you've installed
nvm use <node version>and run
which ghostto see if it's there and setup ghost instance in that environment.
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
nano system/files/your-domain.confto open your NGINX config file.
- 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.