{"_id":"59365227e16643001bac5041","category":{"_id":"59365227e16643001bac5032","version":"59365226e16643001bac5030","project":"543026235eceb608003fde5f","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2017-06-05T10:03:36.502Z","from_sync":false,"order":1,"slug":"getting-started-from-supportghostorgdevelopers","title":"Self-Host Install & Setup"},"project":"543026235eceb608003fde5f","user":"55acc88c6b4ff90d00784b61","parentDoc":null,"version":{"_id":"59365226e16643001bac5030","project":"543026235eceb608003fde5f","__v":1,"createdAt":"2017-06-06T06:56:38.999Z","releaseDate":"2017-06-06T06:56:38.999Z","categories":["59365227e16643001bac5031","59365227e16643001bac5032","59365227e16643001bac5033","59365227e16643001bac5034"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0.0"},"__v":0,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-06-05T15:43:23.140Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":9,"body":"This troubleshooting guide lists common errors faced with installing, upgrading and using Ghost.\n\n<ul>\n<li><a href=\"#section-general\">General</a></li>\n<li><a href=\"#section-sqlite3-errors\">Sqlite3 errors</a></li>\n<li><a href=\"#section-node-issues\">Node errors</a></li>\n<li><a href=\"#section-image-upload-issues\">Image upload issues</a></li>\n<li>[Importer Troubleshooting](doc:the-importer#section-troubleshooting-ghost-imports)</li>\n<li>[Admin Client Troubleshooting](doc:working-with-the-admin-client#section-troubleshooting)</li>\n<li>[Server Troubleshooting](doc:working-with-ghost#troubleshooting)</li>\n</ul>\n\nIf you're still stuck or need more help after reviewing this guide, please head on over and join our public <a href=\"http://slack.ghost.org/\">Slack community</a>, where you'll find a #help channel.\n\n<hr />\n\n## General\n\n### ERROR: Your content path does not exist!\n\nThis 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](doc:configuring-ghost).\n\n### ERROR: URL in config must be provided with protocol\n\nPlease read our [Configuring Ghost](doc:configuring-ghost) guide again.\n\n### ERROR: Unable to open sqlite3 database file for read/write (exit code 236)\n\nThis error indicates that the sqlite3 database file is either not readable or not writable by the user running Ghost. Normally this file exists in <code>content/data/</code> 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](doc:configuring-ghost).\n\n<hr />\n\n## SQLite3 errors\n\nThe 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.\n\nThis 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:\n\n### ERROR: not found, falling back to source compile\n\nIt will then attempt to compile an SQLite3 binary for your architecture from the source. If this doesn't work, it'll then say:\n\n#### ERROR: Build failed\n\nYou may also see errors like <code>npm ERR! sh \"-c\" \"node build.js\" failed with 1</code>\n\nIf 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.\n\nIf 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 <a href=\"https://github.com/TooTallNate/node-gyp#installation\">requirements for node-gyp</a>. Once you've got those installed, you can try it out by running <code>npm install sqlite3 --build-from-source</code>.\n\nIf it won't build you're probably missing one of the python or gcc dependencies, on linux try running <code>sudo npm install -g node-gyp</code>, <code>sudo apt-get install build-essential</code> and <code>sudo apt-get install python-software-properties python g++ make</code> before retrying the build from source.\n\nTo get more information about what's failing, run <code>npm install sqlite3 --loglevel=info</code>. You should then find a more detailed messages explaining:\n\n<ol>\n<li>Why it is falling back to build in the first place usually a \"Not found\" message, look for the lines like:\n\n<code>info using node-pre-gyp:::at:::0.6.7 \nnode-pre-gyp info using node@4.2.4 | linux | arm\nnode-pre-gyp info check checked for \"/home/ghost/ghost/node_modules/sqlite3/lib/binding/node-v46-linux-arm/node_sqlite3.node\" (not found)</code></p></li>\n<li><p>Why the build itself is failing, look for the line like <code>gyp ERR! build error</code>, the issue usually appears just before this.</p></li>\n</ol>\n\n<p>If you need more help, put the full output from <code>npm install sqlite3 --loglevel=info</code> into a gist and post it in the #help channel on <a href=\"https://slack.ghost.org/\">slack</a>.\n\n<hr />\n\n## Node issues\n\n### ERROR: /usr/local/bin doesn't appear in my $PATH\n\nYou can add it by doing the following:\n\n<ul>\n<li>In your terminal window type <code>cd ~</code>, this will take you to your home directory</li>\n<li>Now type <code>ls -al</code> to show all the files and folders in this directory, including hidden ones</li>\n<li>You should see a file called <code>.profile</code> or <code>.bash_profile</code> if not type <code>touch .bash_profile</code> to create a file</li>\n<li>Next, type <code>open -a Textedit .bash_profile</code> to open the file with Textedit.</li>\n<li>Add <code>export PATH=$PATH:/usr/local/bin/</code> at the end of the file and save it</li>\n<li>This new setting will get loaded when a new terminal starts, so open a new terminal tab or window and type <code>echo $PATH</code> to see that '/usr/local/bin/' is now present.\nGhost will not run with a Node.js version older than 0.10.40.</li>\n</ul>\n\n<hr />\n\n## Image upload issues\n\nImage uploads can be affected by two known incompatibility issues. The first is that nginx has a default upload size limit of 1MB, the second is that some advanced CloudFlare features like Rocket Loader and mirage2 can interfere with Ghost's JavaScript &amp; image handling.\n\nIf you cannot upload images bigger than 1MB (try a small image to see if it works), then you will need to increase the limit by editing your nginx config file, and setting the limit to something else.\n\n<ul>\n<li>Log into your server, and type <code>sudo nano /etc/nginx/conf.d/default.conf</code> to open your config file.</li>\n<li>After the <code>server_name</code> line, add the following: <code>client_max_body_size 10M;</code></li>\n<li>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. </li>\n</ul>\n\nIf you've added CloudFlare to your site &amp; turned on Rocket Loader or mirage2 for the front of your blog, it is recommended that you add a page rule which turns those features off for the path <code>/ghost*</code>, so it doesn't affect the G host admin panel. Having these enabled can cause errors like <code>TypeError: n.item is not a function</code> in the JavaScript console.\n\nIf you're on Ghost(Pro) both nginx and CloudFlare have been configured such that these issues do not occur.","excerpt":"","slug":"troubleshooting-guide","type":"basic","title":"Troubleshooting Guide"}

Troubleshooting Guide


This troubleshooting guide lists common errors faced with installing, upgrading and using Ghost. <ul> <li><a href="#section-general">General</a></li> <li><a href="#section-sqlite3-errors">Sqlite3 errors</a></li> <li><a href="#section-node-issues">Node errors</a></li> <li><a href="#section-image-upload-issues">Image upload issues</a></li> <li>[Importer Troubleshooting](doc:the-importer#section-troubleshooting-ghost-imports)</li> <li>[Admin Client Troubleshooting](doc:working-with-the-admin-client#section-troubleshooting)</li> <li>[Server Troubleshooting](doc:working-with-ghost#troubleshooting)</li> </ul> If you're still stuck or need more help after reviewing this guide, please head on over and join our public <a href="http://slack.ghost.org/">Slack community</a>, where you'll find a #help channel. <hr /> ## General ### 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](doc:configuring-ghost). ### ERROR: URL in config must be provided with protocol Please read our [Configuring Ghost](doc: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 <code>content/data/</code> 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](doc:configuring-ghost). <hr /> ## 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 <code>npm ERR! sh "-c" "node build.js" failed with 1</code> 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 <a href="https://github.com/TooTallNate/node-gyp#installation">requirements for node-gyp</a>. Once you've got those installed, you can try it out by running <code>npm install sqlite3 --build-from-source</code>. If it won't build you're probably missing one of the python or gcc dependencies, on linux try running <code>sudo npm install -g node-gyp</code>, <code>sudo apt-get install build-essential</code> and <code>sudo apt-get install python-software-properties python g++ make</code> before retrying the build from source. To get more information about what's failing, run <code>npm install sqlite3 --loglevel=info</code>. You should then find a more detailed messages explaining: <ol> <li>Why it is falling back to build in the first place usually a "Not found" message, look for the lines like: <code>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)</code></p></li> <li><p>Why the build itself is failing, look for the line like <code>gyp ERR! build error</code>, the issue usually appears just before this.</p></li> </ol> <p>If you need more help, put the full output from <code>npm install sqlite3 --loglevel=info</code> into a gist and post it in the #help channel on <a href="https://slack.ghost.org/">slack</a>. <hr /> ## Node issues ### ERROR: /usr/local/bin doesn't appear in my $PATH You can add it by doing the following: <ul> <li>In your terminal window type <code>cd ~</code>, this will take you to your home directory</li> <li>Now type <code>ls -al</code> to show all the files and folders in this directory, including hidden ones</li> <li>You should see a file called <code>.profile</code> or <code>.bash_profile</code> if not type <code>touch .bash_profile</code> to create a file</li> <li>Next, type <code>open -a Textedit .bash_profile</code> to open the file with Textedit.</li> <li>Add <code>export PATH=$PATH:/usr/local/bin/</code> at the end of the file and save it</li> <li>This new setting will get loaded when a new terminal starts, so open a new terminal tab or window and type <code>echo $PATH</code> to see that '/usr/local/bin/' is now present. Ghost will not run with a Node.js version older than 0.10.40.</li> </ul> <hr /> ## Image upload issues Image uploads can be affected by two known incompatibility issues. The first is that nginx has a default upload size limit of 1MB, the second is that some advanced CloudFlare features like Rocket Loader and mirage2 can interfere with Ghost's JavaScript &amp; image handling. If you cannot upload images bigger than 1MB (try a small image to see if it works), then you will need to increase the limit by editing your nginx config file, and setting the limit to something else. <ul> <li>Log into your server, and type <code>sudo nano /etc/nginx/conf.d/default.conf</code> to open your config file.</li> <li>After the <code>server_name</code> line, add the following: <code>client_max_body_size 10M;</code></li> <li>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. </li> </ul> If you've added CloudFlare to your site &amp; turned on Rocket Loader or mirage2 for the front of your blog, it is recommended that you add a page rule which turns those features off for the path <code>/ghost*</code>, so it doesn't affect the G host admin panel. Having these enabled can cause errors like <code>TypeError: n.item is not a function</code> in the JavaScript console. If you're on Ghost(Pro) both nginx and CloudFlare have been configured such that these issues do not occur.