GitHub
Work in Progress

These guides are still a work in progress and may change as we improve the documentation. Please check back later for updates.

LocoMotion encourages powerful debugging and troubleshooting tools to keep your development workflow fast and efficient.

Local Development Troubleshooting

A smooth developer experience starts with great debugging tools and fast feedback loops. This guide walks you through setting up essential tools such as ruby-debug, BetterErrors, Web Console, and Hot-reloading with Foreman/esbuild.

1. ruby-debug (built-in)

Rails 7+ ships with the debug gem (successor to byebug). It’s already in your Gemfile, but here’s a refresher on usage.

# Set a breakpoint anywhere in your code
debugger

# Then run your server (or tests) and execution will pause here

When execution stops, you can inspect variables, step through code, and even evaluate Ruby expressions.

Running in Docker

If you are using the LocoMotion Docker setup, Rails will automatically start a remote debugger.

After adding a debugger breakpoint and refreshing the browser, the request will appear to hang. Open another terminal and run:

make app-debug

This command attaches to the remote debugger inside the container so you can step through code just like you would locally.

2. BetterErrors + binding_of_caller

For richer error pages, add the following gems to your development group:

# Gemfile
group :development do
  gem "better_errors"
  gem "binding_of_caller"
end

After running bundle install, restart your Rails server. You will now see an interactive stack trace page whenever an exception is raised.

BetterErrors – Screenshot showing an error within an application.
Using with Docker

When running inside Docker, BetterErrors will refuse connections from the host machine. Make sure to add the following to config/environments/development.rb:

# Allow BetterErrors to render
BetterErrors::Middleware.allow_ip! "0.0.0.0/0"

Restart your container (e.g. make app-restart) and refresh the page to get the fully-featured error screen.

Security Note

BetterErrors is development-only. It should never run in production.

3. Web Console

Rails ships with Web Console which inserts an IRB prompt right into your browser whenever an exception is raised or when you call the console view helper.

It is included by default in new Rails applications and enabled in the development environment.

Allowing Web Console inside Docker

When Rails is executed inside Docker you will usually see a line like this in the logs:

Cannot render console from 172.23.0.1! Allowed networks: 127.0.0.0/127.255.255.255, ::1

Add the following to config/environments/development.rb:

# Fix console permissions for Docker so Web Console works no matter the IP address
config.web_console.permissions = "0.0.0.0/0"

Restart the app (using make app-restart) and refresh the page – the interactive console should now appear whenever there is an error.

To use Web Console manually inside a view, call the console helper. 

- # You can access the context at the point `console` is called
- my_var = 42

- console # Opens a live console in the rendered view (my_var will be available)
Web Console – Screenshot showing an IRB prompt in the rendered view.

4. Hot-reloading with Foreman, esbuild, & hotwire-livereload

For a tight feedback loop on JS/CSS changes we recommend running a Procfile with Foreman (or bin/dev from Rails 7):

# Procfile.dev
web: rails server -b 0.0.0.0
js: esbuild app/javascript/*.* --bundle --watch
css: tailwindcss -i ./app/assets/stylesheets/application.tailwind.css -o ./app/assets/builds/application.css --watch

And for hot reloading (so you don't even have to refresh your page), just add the hotwire-livereload gem to your Gemfile (in the development group).

# Gemfile
group :development do
  gem "hotwire-livereload"
end

Then start everything with:

bin/dev

Your browser will auto-refresh as you edit any of your files (HAML, JS, CSS, etc)!

5. Troubleshooting Tips

  • Use Rails.logger.debug to print structured output.
  • Tail logs with:
rails logs -f
  • If containers misbehave, rebuild with make dev or prune Docker caches.
Previous
Haml
Made with by Profoundry .
Copyright © 2023-2025 Profoundry LLC.
All rights reserved.
to select
to navigate
esc to close