Docs
Troubleshooting

Troubleshooting

Running into issues? Here are solutions to the most common problems.

Installation Issues

Build errors during installation

Symptom: You see JavaScript build errors when running rails railsui:install.

Cause: This typically happens with JS bundler setups (esbuild, webpack, etc.) when the initial build runs before dependencies are installed.

Solution: These errors are usually harmless. The installation continues and installs the required packages. Run bin/dev after installation completes. The errors should be gone.

cssbundling-rails conflict

Symptom: Warning about cssbundling-rails being detected during installation.

Cause: Rails UI uses the tailwindcss-rails gem for CSS, which conflicts with cssbundling-rails Tailwind setup.

Solution: Run the migration task after installing Rails UI:

rails railsui:migrate_to_tailwindcss_rails

This removes Tailwind from your package.json and switches to the faster tailwindcss-rails gem.

Styles not loading

Symptom: The page loads but without any styling, just plain HTML.

Causes and solutions:

  • Tailwind not building: Make sure you're running bin/dev instead of rails server. The Procfile.dev runs the Tailwind watcher alongside Rails.
  • Missing stylesheet link: Check your layout includes <%= stylesheet_link_tag "tailwind" %>
  • Build output missing: Check that app/assets/builds/tailwind.css exists. If not, run rails tailwindcss:build

Styling Issues

Dark mode not working

Symptom: Dark mode classes aren't applying when you toggle dark mode.

Causes and solutions:

  • Missing dark class on HTML: Tailwind's dark mode requires class="dark" on the <html> element. Check your layout or dark mode toggle implementation.
  • CSS not including dark variants: Ensure your Tailwind config includes dark mode. Rails UI themes configure this automatically.

To toggle dark mode with JavaScript:

rails railsui:migrate_to_tailwindcss_rails
// Toggle dark mode
document.documentElement.classList.toggle('dark')

// Or set based on preference
if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
  document.documentElement.classList.add('dark')
}

Form styles not applying

Symptom: Forms look unstyled or don't match the theme.

Solutions:

  • Use the form builder: Specify builder: Railsui::FormBuilder in your form_with call
  • Or use CSS classes: Apply form-input, form-label, form-select classes manually
<%= form_with model: @user, builder: Railsui::FormBuilder do |form| %>
  <%= form.text_field :name, label: "Name" %>
  <%= form.submit "Save" %>
<% end %>
rails railsui:migrate_to_tailwindcss_rails
// Toggle dark mode
document.documentElement.classList.toggle('dark')

// Or set based on preference
if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
  document.documentElement.classList.add('dark')
}

Custom styles getting overwritten

Symptom: Your customizations disappear after running rails railsui:update.

Cause: Configuration updates overwrite files in app/views/rui and app/assets/stylesheets/railsui/.

Solution: Copy views to your own directory before customizing:

<%= form_with model: @user, builder: Railsui::FormBuilder do |form| %>
  <%= form.text_field :name, label: "Name" %>
  <%= form.submit "Save" %>
<% end %>
# Copy a page to customize
cp app/views/rui/pages/dashboard.html.erb app/views/pages/dashboard.html.erb

# Your custom version won't be overwritten
// Toggle dark mode
document.documentElement.classList.toggle('dark')

// Or set based on preference
if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
  document.documentElement.classList.add('dark')
}

For CSS customizations, add them to app/assets/stylesheets/application.css or create a separate file that won't be overwritten.

JavaScript Issues

Stimulus controllers not connecting

Symptom: Interactive components (dropdowns, modals, etc.) don't respond to clicks.

Causes and solutions:

  • Controllers not registered: Check that railsui-stimulus controllers are imported and registered in your JavaScript entry point
  • Turbo caching issue: If using Turbo, ensure controllers reconnect on navigation. Add data-turbo-permanent to persistent elements if needed.
  • Console errors: Check browser console for JavaScript errors that might prevent execution

Verify controllers are registered:

<%= form_with model: @user, builder: Railsui::FormBuilder do |form| %>
  <%= form.text_field :name, label: "Name" %>
  <%= form.submit "Save" %>
<% end %>
# Copy a page to customize
cp app/views/rui/pages/dashboard.html.erb app/views/pages/dashboard.html.erb

# Your custom version won't be overwritten
// app/javascript/controllers/index.js
import { application } from "./application"
import { RailsuiDropdown, RailsuiModal } from "railsui-stimulus"

application.register("railsui-dropdown", RailsuiDropdown)
application.register("railsui-modal", RailsuiModal)

Importmap resolution errors

Symptom: Console shows "Failed to resolve module specifier" errors.

Cause: The package isn't pinned in your importmap.

Solution: Pin the missing package:

<%= form_with model: @user, builder: Railsui::FormBuilder do |form| %>
  <%= form.text_field :name, label: "Name" %>
  <%= form.submit "Save" %>
<% end %>
./bin/importmap pin railsui-stimulus
// app/javascript/controllers/index.js
import { application } from "./application"
import { RailsuiDropdown, RailsuiModal } from "railsui-stimulus"

application.register("railsui-dropdown", RailsuiDropdown)
application.register("railsui-modal", RailsuiModal)

Check your config/importmap.rb to verify the pin was added.

Theme Issues

Wrong theme showing

Symptom: The wrong theme is displayed after changing themes.

Solution: Run the update task to apply theme changes:

<%= form_with model: @user, builder: Railsui::FormBuilder do |form| %>
  <%= form.text_field :name, label: "Name" %>
  <%= form.submit "Save" %>
<% end %>
rails railsui:update
// app/javascript/controllers/index.js
import { application } from "./application"
import { RailsuiDropdown, RailsuiModal } from "railsui-stimulus"

application.register("railsui-dropdown", RailsuiDropdown)
application.register("railsui-modal", RailsuiModal)

Then restart your server with bin/dev.

Colors not matching theme

Symptom: Primary or secondary colors don't match what you configured.

Solution: Check your theme.css file for the color definitions:

<%= form_with model: @user, builder: Railsui::FormBuilder do |form| %>
  <%= form.text_field :name, label: "Name" %>
  <%= form.submit "Save" %>
<% end %>
rails railsui:update
// app/javascript/controllers/index.js
import { application } from "./application"
import { RailsuiDropdown, RailsuiModal } from "railsui-stimulus"

application.register("railsui-dropdown", RailsuiDropdown)
application.register("railsui-modal", RailsuiModal)
/* app/assets/stylesheets/railsui/theme.css */
@theme {
  --color-primary-500: oklch(0.5854 0.2041 277.12);
  --color-primary-600: oklch(0.5106 0.2301 276.97);
  /* ... */
}

After editing, the Tailwind watcher should pick up changes automatically. If not, restart bin/dev.

Production Issues

Assets not compiling for production

Symptom: Styles or JavaScript missing in production.

Solution: Ensure assets are precompiled during deployment:

<%= form_with model: @user, builder: Railsui::FormBuilder do |form| %>
  <%= form.text_field :name, label: "Name" %>
  <%= form.submit "Save" %>
<% end %>
RAILS_ENV=production rails assets:precompile
// app/javascript/controllers/index.js
import { application } from "./application"
import { RailsuiDropdown, RailsuiModal } from "railsui-stimulus"

application.register("railsui-dropdown", RailsuiDropdown)
application.register("railsui-modal", RailsuiModal)
/* app/assets/stylesheets/railsui/theme.css */
@theme {
  --color-primary-500: oklch(0.5854 0.2041 277.12);
  --color-primary-600: oklch(0.5106 0.2301 276.97);
  /* ... */
}

Most deployment platforms (Heroku, Render, Fly.io) run this automatically. Check your deployment logs for asset compilation errors.

Tailwind purging needed classes

Symptom: Some styles work in development but are missing in production.

Cause: Tailwind purges unused classes in production. Dynamic class names aren't detected.

Solution: Avoid dynamic class construction:

<!-- Bad: Tailwind can't detect this -->
<div class="text-<%= color %>-500">

<!-- Good: Full class names are detectable -->
<% if color == "red" %>
  <div class="text-red-500">
<% else %>
  <div class="text-blue-500">
<% end %>
RAILS_ENV=production rails assets:precompile
// app/javascript/controllers/index.js
import { application } from "./application"
import { RailsuiDropdown, RailsuiModal } from "railsui-stimulus"

application.register("railsui-dropdown", RailsuiDropdown)
application.register("railsui-modal", RailsuiModal)
/* app/assets/stylesheets/railsui/theme.css */
@theme {
  --color-primary-500: oklch(0.5854 0.2041 277.12);
  --color-primary-600: oklch(0.5106 0.2301 276.97);
  /* ... */
}

Or add commonly used dynamic classes to your safelist in tailwind.config.js.

Still stuck?

If you can't find a solution here:

When reporting an issue, please include:

  • Rails version (rails -v)
  • Rails UI version (bundle show railsui)
  • Build mode (nobuild or build)
  • The error message or unexpected behavior
  • Steps to reproduce
FAQs

On this page

Get all updates directly to your inbox.
Sign up for the newsletter.

    We won't send you spam. Unsubscribe at any time.