Debug checklist

As quick checklist to help you debug.

There's nothing more bittersweet than finally solving a bug that you've been stuck on for hours, only to realize that you were on the wrong tab or git branch. We've all been there, and I've made this quick checklist to go through each time something doesn't make sense.

Check your URL

If you want to check local changes (most likely), make sure you're on http://localhost:3000 or whatever your port is, and not the production site.

Check your git branch

Take a second to run a quick git status in your console to ensure that you're working on the right branch and have the latest changes that you expect.

Check your console output

Your Webpack, Rails, etc. server may have some helpful messages on your local and browser console - be sure to check both.

Check if the problem is fixed after updating your packages

I was once stuck on an UglifierJS bug that was escaping the text wrong in a Rails app. I struggled for days until I tried updating the package (from version 2.x.x to 4.x.x) and the problem magically disappeared!

Important note: follow "semver" (semantic versioning) when upgrading packages and check the package's changelog when upgrading from a major version like I did to ensure nothing else gets broken.

Restart your app

Sometimes it just works. Maybe you updated your Webpack config and it's not reflecting those changes, etc. Restarting the server will give your app a chance to recompile from scratch and make sure you're looking at the latest code that you have available locally.


If you have a production rails app and make some database migrations to the local database, make sure you migrate your production database too!


We all get in the weeds from time to time, especially as apps get bigger, accumulate more technical debt and we have to update legacy code. So before taking a deep dive down the rabbit hole the next time you have a confusing bug, double check this list to make sure it's not just a simple fix. SL

Subscribe to Sean W. Lawrence

Don’t miss out on the latest issues. Sign up now to get access to the library of members-only issues.