Tips for dealing with bugs breaking your Discourse installation

Hey everyone,

I wanted to share some tips you might find useful if you are ever dealing with issues on your local Discourse installation.

As you begin developing theme components and plugins, there may be some code that could potentially break your Discourse installation or at least certain functionality in it. This could also happen if you install someone else’s theme component/plugin that may have old code or bad code that breaks something. In such cases, below are some tips to help you solve any problems.

:thinking: If something isn’t working right and you are not sure what plugin/theme is affecting the issue:

  1. Navigate to the page where the issue is happening.
  2. Right Click → Inspect → Select Console Pane
    • or use Keyboard Shortcut: Option + ⌘ + J (on macOS), or Shift + CTRL + J (on Windows/Linux).

This is your browser’s developer tools/console. Look in here for any errors or warnings that may give an indication as to what is causing the issue. In the screenshot below you’ll see that the left side shows the error and to the far right you can see what file is causing the issue. Clicking on that link to the file will direct you to the portion of the code where the error is appearing. This may give you a clue to what is causing the issue.

:bug: If a theme/plugin is causing a bug or Discourse won’t even load a page due to a bug:

Make use of Discourse’s safe-mode feature.

Navigate to: http://localhost:4200/safe-mode, where you can Disable your current theme, unofficial plugins and/or all plugins.

More information about this feature here:

:sponge: You need to wipe all your data and start fresh with your Discourse installation:

If you need to start fresh with your Discourse installation run these following commands in your command line:

:warning: First make sure you are not running your rails server or ember-cli currently

  1. Navigate to the folder where your Discourse installation is (usually cd ~/discourse)
  2. Drop the database, recreate it and migrate the data: (Note this will wipe all your data on your local Discourse)
./bin/rake db:drop db:create db:migrate
  1. Pull the latest Discourse commit:
git pull
  1. Migrate the database:
./bin/rake db:migrate
  1. Start your server to test if it works:
bundle exec rails server
  1. Stop your server:

Ctrl + C on your keyboard

  1. Create an admin account:
RAILS_ENV=development bundle exec rake admin:create

Follow the prompts to fill in your email, password, and repeat your password.

  1. Start your server
bin/rails s
  1. Start the ember cli:
  1. Navigate to http://localhost:4200 and you should have a fresh installation of Discourse.