Common Issues & Quick Fixes

Quick troubleshooting reference for React on Rails. For in-depth debugging, see the Troubleshooting Guide.

Diagnostic Command

Before diving into specific issues, run the doctor command:

bundle exec rake react_on_rails:doctor

# For more detailed output:
VERBOSE=true bundle exec rake react_on_rails:doctor

This checks your environment, dependencies, and configuration for common problems.

Component Not Rendering

Symptoms: Blank space where component should be, no console errors

Quick Checklist

Component registered?
- With auto-bundling: Component must be in a ror_components directory
- Without auto-bundling: Check for ReactOnRails.register({ ComponentName })

Name matches exactly?

<%# The name must match exactly (case-sensitive, check for typos) %>
<%= react_component("MyComponent", props: {}) %>

Bundle loaded in layout?

<%# In app/views/layouts/application.html.erb <head> %>
<%= javascript_pack_tag %>

Auto-bundling enabled? Check config.auto_load_bundle = true in config/initializers/react_on_rails.rb

Note: The generator sets this automatically in v16.0+, so you shouldn't need to add it manually for new installations.
Check browser console for JavaScript errors

Hydration Mismatch Errors

Symptoms: Console warning about hydration, content flickers on page load

Common Causes

Using non-deterministic values in render:

import { useState, useEffect } from 'react';

// BAD - different on server vs client
const BadComponent = () => <div>{Date.now()}</div>;

// GOOD - move to useEffect
const GoodComponent = () => {
  const [time, setTime] = useState(null);
  useEffect(() => setTime(Date.now()), []);
  return <div>{time}</div>;
};

Accessing browser APIs during render:

// BAD
const width = window.innerWidth;

// GOOD - guard with typeof check
const width = typeof window !== 'undefined' ? window.innerWidth : 0;

Props differ between server and client:
- Ensure the exact same props are passed in both renders
- Check for timezone differences in date formatting

SSR Fails / Server Rendering Errors

Symptoms: Error during server render, works fine client-side only

Debug Steps

# Run diagnostics
bundle exec rake react_on_rails:doctor

# Check server bundle exists (location may vary based on Shakapacker config)
ls -la public/packs/server-bundle*.js

Common Causes

Component uses browser APIs:

// These don't exist on server - guard them
if (typeof window !== 'undefined') {
  // Browser-only code
}

Missing server bundle configuration:

# config/initializers/react_on_rails.rb
ReactOnRails.configure do |config|
  config.server_bundle_js_file = "server-bundle.js"
end

Async operations in render:
- ExecJS doesn't support async/await in server rendering
- Use React on Rails Pro for async SSR support

"Module not found" / Webpack Errors

Symptoms: Build fails, can't resolve imports

Solutions

# Clear and reinstall dependencies
rm -rf node_modules
yarn install  # or: npm install, pnpm install

# Rebuild assets
yarn build  # or: npm run build, pnpm build

# Check Shakapacker config
cat config/shakapacker.yml

Common Causes

npm package not installed:

yarn add react-on-rails
# or: npm install react-on-rails
# or: pnpm add react-on-rails

Incorrect import path:

// Check the actual file location matches your import
import MyComponent from '../components/MyComponent';

"Cannot find module 'react-on-rails'"

Symptoms: JavaScript error about missing react-on-rails module

Solution

The gem and npm package must both be installed:

# Install npm package
yarn add react-on-rails
# or: npm install react-on-rails
# or: pnpm add react-on-rails

Hot Reloading Not Working

Symptoms: Changes don't appear without full page refresh

Checklist

Using bin/dev?

# This starts both Rails and webpack-dev-server
bin/dev

Check webpack-dev-server is running:
- Look for webpack output in terminal
- Check http://localhost:3035 responds

Verify HMR configuration in shakapacker.yml:

development:
  dev_server:
    hmr: true

Assets Not Compiling in Production

Symptoms: Missing JavaScript/CSS in production

Checklist

# Ensure assets compile
RAILS_ENV=production bundle exec rake assets:precompile

# Check output directory
ls -la public/packs/

Common Causes

Missing NODE_ENV:

NODE_ENV=production RAILS_ENV=production rake assets:precompile

Build dependencies missing in production:
- Check package.json dependencies vs devDependencies

TypeError: Cannot read property of undefined

Symptoms: Runtime error when accessing props

Common Causes

Props not passed correctly from Rails:

<%# Make sure props is a hash %>
<%= react_component("MyComponent", props: { user: @user.as_json }) %>

Destructuring undefined props:

// Add default values
const MyComponent = ({ user = {} }) => {
  return <div>{user.name || 'Anonymous'}</div>;
};

Still Stuck?

Check the detailed Troubleshooting Guide
Search GitHub Issues
Ask in GitHub Discussions
Join React + Rails Slack
Professional support: [email protected]