Installation Issues

Rails Pulse Not Detected

Symptom: Running upgrade generator shows “Rails Pulse installation not detected”

Solution: Run the install generator first:

rails generate rails_pulse:install
rails db:migrate

Migration Already Exists Error

Symptom: Error when running the install generator about existing migration

Solution: Check if the migration already ran:

# For single database
rails db:migrate:status

# For separate database
rails db:migrate:status:rails_pulse

If the migration shows as “up”, you’re already installed. If “down”, run rails db:migrate.

Database Already Exists Error

Symptom: Error during separate database setup about database already existing

Solution: For a first install use db:prepare instead of db:create:

rails db:prepare

This command safely creates the database if it doesn’t exist, or loads the schema if it does. For upgrades of an existing separate database use rails db:migrate:rails_pulse instead.

Missing Columns After Gem Update

Symptom: Errors about missing columns after updating the Rails Pulse gem

Solution: Run the upgrade generator to copy new migrations and detect missing columns:

rails generate rails_pulse:upgrade
rails db:migrate                  # separate database: rails db:migrate:rails_pulse
rails rails_pulse:migrate_routes  # when upgrading from 0.3.x

See Upgrading.

Upgrade Issues

Action Column Empty / Banner Says Run migrate_routes

Symptom: After upgrading to 0.4.0 the routes page shows an empty Action column, GET and POST on the same path appear as separate rows, and the dashboard shows a banner with a command.

Solution: The schema migration does not backfill route identity. Run the one-time task:

rails rails_pulse:migrate_routes

It prints how many routes it updated, merged, and skipped. If it reports duplicate null-action paths it could not resolve, remove the duplicate RailsPulse::Route rows manually and re-run it.

500 Errors on Routes Page After Upgrade

Symptom: /rails_pulse/routes returns 500 after deploying 0.4.0, or request tracking silently stops in some processes.

Solution: A 0.3.x process is still running against the migrated schema. 0.4.0 drops rails_pulse_routes.method, so old and new processes cannot share a database. Restart all web and worker processes together rather than rolling them.

Dashboard Returns 503 and Tracking Has Paused

Symptom: Every dashboard page returns 503 with a list of upgrade commands, and the log shows one RailsPulse warning that the schema is behind the gem.

Solution: The gem was deployed before its migrations ran, or a process was restarted against tables an older gem created. Run the commands the page lists (rails generate rails_pulse:upgrade, rails db:migrate or rails db:migrate:rails_pulse, then rails rails_pulse:migrate_routes once after the route identity migrations) and restart. rails rails_pulse:status shows exactly which table or column is missing. To turn the guard off entirely, set config.schema_check_enabled = false.

unterminated string meets end of file in Upgrade Migration

Symptom: rails db:migrate fails to load upgrade_rails_pulse_tables.rb.

Solution: This was a bug in 0.4.0.pre.1’s generator when a column comment contained escaped quotes. Update to 0.4.0 (or 0.4.0.pre.2 or later), delete the broken migration, and re-run rails generate rails_pulse:upgrade.

message type 0x5a arrived from server while idle in Tests

Symptom: A PostgreSQL test suite hangs or fails randomly with message type 0x5a arrived from server while idle or server sent data ("D" message) without prior row description after installing Rails Pulse.

Solution: Transactional tests share one database connection across threads, so the background writer interleaves with the test’s own statements. Write inline in tests:

# config/initializers/rails_pulse.rb
config.async = false if Rails.env.test?

The install generator adds this line for new apps, and rails generate rails_pulse:upgrade appends it to an existing initializer that does not mention config.async. The tracker also writes inline whenever it detects a connection shared across threads, so this setting makes the behaviour explicit rather than being the only safeguard.

relation already exists on a Separate Database

Symptom: rails db:migrate or db:migrate:rails_pulse fails with relation "rails_pulse_routes" already exists.

Solution: Rails dumped a structure file for the Pulse database and reloaded it. Add schema_dump: false to the rails_pulse entry in config/database.yml and delete db/rails_pulse_structure.sql.

403 or HTTP Basic Prompt in Staging After Upgrade

Symptom: The dashboard asks for a username and password, or returns 403, in an environment where it used to load without authentication.

Solution: Since 0.4.0 authentication is on outside development and test, not only in production, and hooks fail closed. Configure a gate:

config.authorize = ->(controller) { controller.current_user&.admin? }

or, if you really want it off in that environment, set config.authentication_enabled = false there. See Authentication.

assets:precompile Runs Out of Memory or Times Out

Symptom: Deploys fail during assets:precompile on a small host after adding Rails Pulse.

Solution: Remove any rails-pulse.js / rails-pulse.css entries from config.assets.precompile. The gem no longer registers its bundle with Sprockets; assets:precompile copies the pre-built files into public/assets via rails_pulse:install_assets without re-minifying them.

Dashboard Issues

Dashboard Not Loading / 404 Error

Symptom: Visiting /rails_pulse shows 404 or routing error

Solution: Ensure Rails Pulse is mounted in your routes:

Rails.application.routes.draw do
  mount RailsPulse::Engine => "/rails_pulse"
end

Restart your Rails server after adding the route.

Dashboard Shows No Data

Symptom: Dashboard loads but shows empty charts and tables

Possible causes and solutions:

1. Rails Pulse is disabled - Check your initializer:

   RailsPulse.configure do |config|
     config.enabled = true  # Make sure this is true
   end

2. No traffic yet - Generate some requests to your application, then check the dashboard again

3. Wrong database connection - If using separate database, verify connects_to configuration matches your database.yml

4. Data retention period expired - Check if cleanup removed all data. Adjust retention period:

   RailsPulse.configure do |config|
     config.full_retention_period = 30.days  # Increase if needed
   end

Charts Not Rendering

Symptom: Dashboard loads but charts are missing or broken

Solution: This is typically a JavaScript error. Check your browser console for errors and ensure:

• Your Content Security Policy (CSP) allows Rails Pulse assets
• No JavaScript conflicts with other gems or libraries
• Rails Pulse assets are properly compiled (if using asset pipeline)

Tracking Issues

Requests Not Being Tracked

Symptom: Some or all requests aren’t appearing in Rails Pulse

Possible causes and solutions:

1. Routes are ignored - Check ignored routes configuration:

   RailsPulse.configure do |config|
     config.ignored_routes = []  # Check if routes are excluded
     config.track_assets = false  # Asset requests ignored by default
   end

2. Custom mount path not configured - If Rails Pulse is mounted at a custom path:

   RailsPulse.configure do |config|
     config.mount_path = "/admin/monitoring"  # Prevents self-tracking
   end

3. Middleware not loaded - Restart your Rails server to ensure middleware is active

Background Jobs Not Being Tracked

Symptom: Jobs page is missing or shows no data despite running background jobs

Possible causes and solutions:

1. Job tracking disabled - It is off by default, and the Jobs routes are only mounted when it is on:

   RailsPulse.configure do |config|
     config.track_jobs = true
   end

2. Jobs or queues are ignored - Check ignored configuration:

   RailsPulse.configure do |config|
     config.ignored_jobs = []    # Check if job class is excluded
     config.ignored_queues = []  # Check if queue is excluded
   end

3. Job workers need restart - Restart your background job workers (Sidekiq, Solid Queue, etc.)

SQL Queries Not Showing

Symptom: Request details don’t show SQL queries

Possible causes and solutions:

1. Queries are ignored - Check ignored queries configuration:

   RailsPulse.configure do |config|
     config.ignored_queries = []  # Check if queries are excluded
   end

2. No database queries in request - Some requests (redirects, static files) may not execute queries

Exceptions Tab Missing or Empty

Symptom: There is no Exceptions tab, or /rails_pulse/exceptions returns 404

Solution: Exception tracking is off by default for upgraded installs, and the routes are only mounted when it is on:

RailsPulse.configure do |config|
  config.track_exceptions = true
end

Restart web and worker processes. Only unhandled exceptions from requests and failed jobs are captured; exceptions you rescue yourself are not. See Exception Tracking.

Performance Issues

Application Slowdown After Installing

Symptom: Noticeable performance degradation after adding Rails Pulse

Solutions:

1. Use aggressive filtering for high-traffic applications:

   RailsPulse.configure do |config|
     # Ignore low-value routes
     config.ignored_routes = [/^\/assets/, /^\/health/]
     config.track_assets = false
   
     # Disable job argument capture
     config.capture_job_arguments = false
   end

2. Use a separate database to isolate monitoring overhead - see Database documentation

3. Reduce data retention to keep tables smaller:

   RailsPulse.configure do |config|
     config.full_retention_period = 7.days  # Shorter retention
     config.max_table_records = {
       rails_pulse_requests: 5_000,
       rails_pulse_operations: 25_000,
       rails_pulse_queries: 2_000
     }
   end

4. Disable in production if overhead is unacceptable:

   RailsPulse.configure do |config|
     config.enabled = Rails.env.development? || Rails.env.staging?
   end

See the Performance Impact Guide for detailed optimization strategies.

Database Growing Too Large

Symptom: Rails Pulse tables consuming excessive disk space

Solutions:

1. Enable and configure cleanup:

   RailsPulse.configure do |config|
     config.archiving_enabled = true
     config.full_retention_period = 7.days  # Adjust as needed
   end

2. Schedule cleanup job to run daily:

   # In your job scheduler (cron, whenever, etc.)
   RailsPulse::CleanupJob.perform_later

3. Run manual cleanup:

   rails rails_pulse:cleanup

4. Check current database status:

   rails rails_pulse:cleanup_stats

Authentication Issues

Authentication Not Working

Symptom: Dashboard is accessible without authentication despite configuration

Solution: Check that you have not disabled it for the environment (authentication_enabled is on by default outside development and test), and use authorize for predicate-style checks:

RailsPulse.configure do |config|
  config.authorize = ->(controller) { controller.current_user&.admin? }
end

If you use authentication_method, remember that it allows the request when it returns nil without rendering or redirecting. proc { current_user&.admin? } lets signed-out visitors in; put that check in authorize instead.

Restart your server after changing authentication configuration.

Redirect Loop with Authentication

Symptom: Browser shows too many redirects error

Solution: Make sure your authentication redirect doesn’t point back to Rails Pulse:

RailsPulse.configure do |config|
  # Don't redirect to /rails_pulse or you'll create a loop
  config.authentication_redirect_path = "/login"  # Not "/rails_pulse"
end

Current User Not Available

Symptom: Error about undefined method current_user

Solution: Hooks run inside the engine’s controller, which inherits from your ApplicationController’s helpers only when they are defined as controller methods. If current_user lives in a concern or helper the engine cannot see, look the user up explicitly:

RailsPulse.configure do |config|
  config.authorize = ->(controller) {
    user = User.find_by(id: controller.session[:user_id])
    user&.admin?
  }
end

See the Authentication documentation for more examples.

Database Configuration Issues

Separate Database Not Connecting

Symptom: Errors about database connection when using separate database

Solution: Verify your configuration matches between initializer and database.yml:

RailsPulse.configure do |config|
  config.connects_to = {
    database: { writing: :rails_pulse, reading: :rails_pulse }
  }
  # ↑ This name must match the key in database.yml ↓
end

production:
  # ... your main database ...

  rails_pulse:  # ← Must match the name in connects_to
    adapter: postgresql
    database: myapp_rails_pulse_production
    migrations_paths: db/rails_pulse_migrate
    schema_dump: false
    # ... rest of config ...

Connection Fails in CI with Separate Database

Symptom: db:test:prepare fails in CI with an error like:

ActiveRecord::ConnectionNotEstablished: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed: No such file or directory

Solution: In a multi-database setup, DATABASE_URL only overrides the primary database configuration. The rails_pulse entry keeps its database.yml settings, and without a host it tries to connect over a local socket.

Set the connection details explicitly via environment variables instead of relying on DATABASE_URL:

default: &default
  adapter: postgresql
  host: <%= ENV.fetch("DB_HOST", "localhost") %>
  username: <%= ENV.fetch("DB_USERNAME", "postgres") %>
  password: <%= ENV.fetch("DB_PASSWORD", nil) %>

See Running Tests in CI for a full example.

Schema File Missing

Symptom: Error about missing db/rails_pulse_schema.rb

Solution: Don’t delete the schema file - it’s the single source of truth. If accidentally deleted, reinstall:

rails generate rails_pulse:install --force

Migrations Path Not Found

Symptom: Rails can’t find migrations in db/rails_pulse_migrate

Solution: Ensure migrations_paths is set in database.yml:

production:
  rails_pulse:
    adapter: postgresql
    database: myapp_rails_pulse
    migrations_paths: db/rails_pulse_migrate  # Required for separate DB
    schema_dump: false                         # Prevents duplicate table errors

Still Having Issues?

If you can’t find a solution here, we’re happy to help:

Check FAQ

Browse frequently asked questions for quick answers.

View FAQ →

Report an Issue

Found a bug? Report it on GitHub Issues.

GitHub Issues →

When Reporting Issues

Help us help you by including:

• Rails Pulse version (bundle info rails_pulse)
• Rails version (rails -v)
• Ruby version (ruby -v)
• Database adapter (SQLite, PostgreSQL, MySQL)
• Error messages and stack traces
• Relevant configuration from your initializer
• Steps to reproduce the issue