Rails Error Dashboard

Self-hosted error tracking and exception monitoring for Ruby on Rails. Open source, free forever. A Sentry alternative with cause chains, analytics, workflow management, and multi-channel notifications.

Download as .zip Download as .tar.gz View on GitHub

Troubleshooting Guide

Comprehensive troubleshooting guide for Rails Error Dashboard. Solutions to common problems, error messages, and debugging techniques.


Table of Contents


Installation & Setup Issues

Errors Not Being Logged After Installation

Symptoms: Dashboard is accessible but no errors appear.

Solutions:

  1. Verify middleware is installed:
    # In rails console
    Rails.application.config.middleware.to_a.grep(/ErrorCatcher/)
    # Should return: [RailsErrorDashboard::Middleware::ErrorCatcher]
    
  2. Check if middleware is enabled:
    RailsErrorDashboard.configuration.enable_middleware
    # Should return: true
    
  3. Manually trigger an error to test:
    # In rails console
    raise "Test error from console"
    
  4. Check Rails.error subscriber:
    RailsErrorDashboard.configuration.enable_error_subscriber
    # Should return: true
    
  5. Verify database tables exist:
    rails db:migrate:status | grep error_dashboard
    # Should show multiple migrations as "up"
    

Migrations Failing

Problem: rails db:migrate fails with errors.

Solutions:

  1. Check for existing tables:
    rails db
    # Then: \dt error_dashboard*
    
  2. Rollback and re-run:
    rails db:rollback STEP=5
    rails db:migrate
    
  3. Drop and recreate (DEVELOPMENT ONLY):
    rails db:drop db:create db:migrate
    
  4. Check database permissions:
    -- PostgreSQL
    GRANT ALL PRIVILEGES ON DATABASE your_db TO your_user;
    

Dashboard Not Mounted / 404 Error

Problem: Visiting /error_dashboard returns 404.

Solutions:

  1. Verify mount in routes:
    rails routes | grep error_dashboard
    # Should show multiple routes
    
  2. Check config/routes.rb:
    # Should contain:
    mount RailsErrorDashboard::Engine => "/error_dashboard"
    
  3. Restart server after adding mount:
    rails server
    
  4. Check for route conflicts:
    # Look for conflicting /error_dashboard routes
    rails routes | grep /error
    

Configuration Problems

Configuration Not Taking Effect

Problem: Changes to config/initializers/rails_error_dashboard.rb don’t work.

Solutions:

  1. Restart server (required for initializer changes):
    rails server
    
  2. Check file location:
    ls -la config/initializers/rails_error_dashboard.rb
    # File must exist in config/initializers/
    
  3. Check for syntax errors:
    ruby -c config/initializers/rails_error_dashboard.rb
    # Should return: Syntax OK
    
  4. Verify configuration is loaded:
    # In rails console
    RailsErrorDashboard.configuration.inspect
    # Shows all current settings
    

Environment Variables Not Working

Problem: ENV['VARIABLE'] returns nil in configuration.

Solutions:

  1. Verify variable is set:
    echo $SLACK_WEBHOOK_URL
    # Should output the URL
    
  2. Use dotenv-rails in development:
    # Gemfile
    gem 'dotenv-rails', groups: [:development, :test]
    
    # .env file
    SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
    
  3. Provide defaults in config:
    config.slack_webhook_url = ENV.fetch('SLACK_WEBHOOK_URL', nil)
    
  4. Check ENV vars are loaded before Rails:
    # config/application.rb (top of file)
    require 'dotenv/rails-now' if defined?(Dotenv)
    

Custom Severity Rules Not Working

Problem: Custom severity rules aren’t being applied.

Solutions:

  1. Use regex, not strings:
    # CORRECT
    config.custom_severity_rules = {
      /ActiveRecord::RecordNotFound/ => :low,
      /Stripe::/ => :critical
    }
    
    # INCORRECT (won't match)
    config.custom_severity_rules = {
      "ActiveRecord::RecordNotFound" => :low  # String won't match!
    }
    
  2. Test regex patterns:
    # In rails console
    error_class = "ActiveRecord::RecordNotFound"
    /ActiveRecord::RecordNotFound/.match?(error_class)
    # Should return: true
    
  3. Check rule order (first match wins):
    # More specific first
    config.custom_severity_rules = {
      /ActiveRecord::RecordNotFound.*User/ => :high,   # Specific
      /ActiveRecord::RecordNotFound/ => :low           # General
    }
    

Error Logging Issues

Errors Being Logged Multiple Times

Problem: Same error creates multiple entries.

Solutions:

  1. Check hash signature generation:
    # In rails console
    error = RailsErrorDashboard::ErrorLog.last
    error.hash_signature
    # Should be consistent SHA-256 hash
    
  2. Verify deduplication is working:
    # Same error type should increment occurrence_count, not create new record
    error = RailsErrorDashboard::ErrorLog.find_by(error_type: "RuntimeError")
    error.occurrence_count
    # Should be > 1 if error happened multiple times
    
  3. Check for race conditions:
    • Ensure pessimistic locking is working
    • Check database transaction log for conflicts

Background Job Errors Not Logged

Problem: Errors in Sidekiq/Solid Queue jobs don’t appear.

Solutions:

  1. Ensure error subscriber is enabled:
    config.enable_error_subscriber = true
    
  2. Check job adapter error handling:
    # Sidekiq example
    class YourJob < ApplicationJob
      retry_on StandardError, wait: :exponentially_longer
    
      def perform
        # Your code
      end
    end
    
  3. Manually log in job rescue blocks:
    def perform
      # Code
    rescue => e
      RailsErrorDashboard::Commands::LogError.call(exception: e)
      raise # Re-raise to let job adapter handle retry
    end
    

Sampling Too Aggressive

Problem: Too many errors being filtered out.

Solutions:

  1. Check sampling rate:
    RailsErrorDashboard.configuration.sampling_rate
    # 0.1 = 10%, 1.0 = 100%
    
  2. Critical errors always logged (bypass sampling):
    # Set error as critical to bypass sampling
    config.custom_severity_rules = {
      /Payment/ => :critical  # Always logged
    }
    
  3. Adjust rate based on volume:
    # Start high, tune down
    config.sampling_rate = 0.5  # 50%
    
  4. Use conditional sampling:
    config.before_log_callback = lambda do |exception, context|
      # Always log payment errors
      return true if exception.message.include?("Stripe")
    
      # Sample others
      Rails.env.production? ? rand < 0.1 : true
    end
    

Dashboard Access Problems

Authentication Not Working

Problem: Can’t access dashboard with correct credentials.

Solutions:

  1. Check credentials are set:
    # In rails console
    RailsErrorDashboard.configuration.dashboard_username
    RailsErrorDashboard.configuration.dashboard_password
    # Should return configured values (not nil)
    
  2. Verify HTTP Basic Auth header:
    # Test with curl
    curl -u admin:password http://localhost:3000/error_dashboard
    # Should return 200, not 401
    
  3. Clear browser cache (old credentials may be cached):
    • Chrome: Cmd+Shift+Delete → Clear browsing data
    • Or use incognito window
  4. Check for proxy/load balancer stripping Authorization header:
    # Nginx example - ensure proxy passes auth header
    proxy_set_header Authorization $http_authorization;
    proxy_pass_header Authorization;
    

Dashboard Slow to Load

Problem: Dashboard pages take >5 seconds to load.

Solutions:

  1. Enable async logging:
    config.async_logging = true
    
  2. Add database indexes (should be automatic):
    rails db:migrate:status | grep add_indexes
    # Should show "up"
    
  3. Check for N+1 queries:
    # Enable query logging in development
    # config/environments/development.rb
    config.active_record.verbose_query_logs = true
    
  4. Reduce retention period:
    config.retention_days = 30  # Instead of 90
    
  5. Use separate database:
    config.use_separate_database = true
    config.database = :errors
    

Notification Issues

Slack Notifications Not Sending

Problem: Slack notifications configured but not arriving.

Solutions:

  1. Verify notifications are enabled:
    # In rails console
    RailsErrorDashboard.configuration.enable_slack_notifications
    # Should return: true
    
  2. Check webhook URL is set:
    RailsErrorDashboard.configuration.slack_webhook_url
    # Should return your webhook URL
    
  3. Test webhook manually:
    curl -X POST YOUR_WEBHOOK_URL \
      -H 'Content-Type: application/json' \
      -d '{"text": "Test message from Rails Error Dashboard"}'
    # Should receive message in Slack
    
  4. Check background jobs are running:
    # Sidekiq
    ps aux | grep sidekiq
    
    # Solid Queue
    ps aux | grep solid_queue
    
  5. Check failed jobs:
    # Sidekiq
    require 'sidekiq/api'
    Sidekiq::RetrySet.new.size  # Failed jobs
    Sidekiq::DeadSet.new.size   # Dead jobs
    
    # Solid Queue
    SolidQueue::Job.failed.count
    
  6. Verify notification thresholds:
    # Check if error severity matches notification threshold
    config.severity_thresholds[:slack]
    # Returns minimum severity for Slack notifications
    

Email Notifications Not Sending

Problem: Email notifications configured but not arriving.

Solutions:

  1. Check ActionMailer configuration:
    # config/environments/production.rb
    config.action_mailer.delivery_method = :smtp
    config.action_mailer.smtp_settings = {
      address: "smtp.gmail.com",
      port: 587,
      # ...
    }
    
  2. Verify email recipients are set:
    RailsErrorDashboard.configuration.notification_email_recipients
    # Should return: ["team@example.com"]
    
  3. Check email is enabled:
    RailsErrorDashboard.configuration.enable_email_notifications
    # Should return: true
    
  4. Test email delivery:
    # In rails console
    TestMailer.test_email.deliver_now
    

Discord/PagerDuty Notifications Failing

Problem: Discord or PagerDuty webhooks not working.

Solutions:

  1. Check webhook URL format:
    # Discord
    config.discord_webhook_url
    # Should start with: https://discord.com/api/webhooks/
    
    # PagerDuty
    config.pagerduty_integration_key
    # Should be valid integration key
    
  2. Test webhook manually:
    # Discord
    curl -X POST "https://discord.com/api/webhooks/YOUR_WEBHOOK" \
      -H "Content-Type: application/json" \
      -d '{"content": "Test message"}'
    
    # PagerDuty
    curl -X POST "https://events.pagerduty.com/v2/enqueue" \
      -H "Content-Type: application/json" \
      -d '{
        "routing_key": "YOUR_KEY",
        "event_action": "trigger",
        "payload": {
          "summary": "Test",
          "severity": "critical",
          "source": "test"
        }
      }'
    
  3. Check severity filtering (PagerDuty only sends critical):
    # PagerDuty only receives critical errors by default
    config.severity_thresholds[:pagerduty]
    # Should return: :critical
    

Performance Problems

Database Growing Too Large

Problem: Error dashboard database is consuming too much space.

Solutions:

  1. Configure retention policy:
    config.retention_days = 30  # Auto-delete after 30 days
    
  2. Manually clean old errors:
    rails rails_error_dashboard:cleanup_old_errors
    
  3. Limit backtrace lines:
    config.max_backtrace_lines = 20  # Instead of 50
    
  4. Enable sampling:
    config.sampling_rate = 0.1  # Log 10% of non-critical errors
    
  5. Use separate database:
    config.use_separate_database = true
    config.database = :errors
    

Background Jobs Queuing Up

Problem: Error logging jobs piling up in queue.

Solutions:

  1. Check job processor is running:
    # Sidekiq
    bundle exec sidekiq
    
    # Solid Queue
    bin/jobs
    
  2. Increase job concurrency:
    # config/sidekiq.yml
    :concurrency: 10  # Instead of 5
    
  3. Monitor queue size:
    # Sidekiq
    require 'sidekiq/api'
    Sidekiq::Queue.new.size
    
    # Solid Queue
    SolidQueue::Job.pending.count
    
  4. Consider sync logging temporarily:
    config.async_logging = false  # For debugging
    

Advanced Features Not Working

Baseline Alerts Not Triggering

Problem: Baseline monitoring enabled but no alerts.

Solutions:

  1. Check feature is enabled:
    RailsErrorDashboard.configuration.enable_baseline_alerts
    # Should return: true
    
  2. Verify minimum data exists:
    • Need at least 7 days of error history
    • Need at least 10 occurrences of an error type
  3. Check threshold settings:
    config.baseline_alert_threshold_std_devs
    # Default: 2.0 (2 standard deviations)
    # Lower = more sensitive, Higher = less sensitive
    
  4. Check cooldown period:
    config.baseline_alert_cooldown_minutes
    # Default: 120 (2 hours between alerts for same error)
    
  5. Verify severity filter:
    config.baseline_alert_severities
    # Default: [:critical, :high]
    # Only these severities trigger baseline alerts
    

Similar Errors Not Appearing

Problem: Fuzzy matching enabled but no similar errors shown.

Solutions:

  1. Check feature is enabled:
    RailsErrorDashboard.configuration.enable_similar_errors
    # Should return: true
    
  2. Verify enough errors exist:
    • Need at least 10 different error types
    • Similarity requires variation in messages/backtraces
  3. Check similarity thresholds:
    • Jaccard similarity: 70% match required
    • Levenshtein distance: Calculated proportionally
  4. Manually trigger calculation:
    # In rails console
    error = RailsErrorDashboard::ErrorLog.last
    similar = RailsErrorDashboard::Queries::SimilarErrors.call(error.id)
    similar.inspect
    

Platform Comparison Shows No Data

Problem: Platform comparison enabled but shows empty.

Solutions:

  1. Check feature is enabled:
    RailsErrorDashboard.configuration.enable_platform_comparison
    # Should return: true
    
  2. Verify platform data exists:
    # In rails console
    RailsErrorDashboard::ErrorLog.pluck(:platform).uniq
    # Should return: ["iOS", "Android", "Web", etc.]
    
  3. Check platform detection:
    • Ensure errors are tagged with platform
    • Mobile apps should send platform parameter
    • Browser gem detects web platforms

Deep Debugging Issues (v0.4.0)

Local Variables Not Showing on Error Detail Page

Problem: enable_local_variables is enabled but errors don’t show variable data.

Solutions:

  1. Verify feature is enabled:
    RailsErrorDashboard.configuration.enable_local_variables
    # Should return: true
    
  2. Check that the error was captured AFTER enabling — existing errors won’t have variables. Only new errors get variable data.

  3. Some exceptions don’t have local variables — if the exception is raised in C code or a native extension, TracePoint may not capture locals.

Swallowed Exceptions Page Empty

Problem: /errors/swallowed_exceptions shows no data.

Solutions:

  1. Check Ruby version — requires Ruby 3.3+ for TracePoint(:rescue). On Ruby < 3.3, the feature is auto-disabled.

  2. Verify feature is enabled:
    RailsErrorDashboard.configuration.detect_swallowed_exceptions
    # Should return: true
    
  3. Wait for flush interval — data is flushed to the database every swallowed_exception_flush_interval seconds (default: 60). Check back after a minute.

  4. Check threshold — only locations where the rescue ratio exceeds swallowed_exception_threshold (default: 0.95) are shown.

Diagnostic Dump Button Not Working

Problem: “Capture Dump” button doesn’t create a dump.

Solutions:

  1. Verify feature is enabled:
    RailsErrorDashboard.configuration.enable_diagnostic_dump
    # Should return: true
    
  2. Try the rake taskrails error_dashboard:diagnostic_dump to verify the feature works outside the dashboard.

  3. Check browser console — the button uses a <form> POST, not a JavaScript link. If Turbo is interfering, check for JS errors.

Crash Capture Not Importing on Boot

Problem: Process crashed but no crash error appeared after restart.

Solutions:

  1. Check crash file path — look for JSON files in Dir.tmpdir (or your custom crash_capture_path).

  2. Verify the crash was an unhandled exceptionat_exit only captures when $! is set (an exception terminated the process). Clean exits via exit(0) or SIGTERM don’t trigger it.

  3. Check file permissions — the process needs write permission to the crash capture path.


Source Code Integration Issues

Source Code Not Showing

Problem: “View Source” button not appearing on error details.

Quick Check:

# In Rails console
RailsErrorDashboard.configuration.enable_source_code_integration
# Should return: true

Common Causes:

  1. Feature not enabled in configuration
  2. File path is outside Rails.root
  3. Frame category is not :app (gem frames don’t show source)
  4. File doesn’t exist or isn’t readable

Solutions:

  1. Enable in initializer:
    config.enable_source_code_integration = true
    
  2. Restart Rails server (required for initializer changes)

  3. Verify file exists and is readable:
    ls -la app/controllers/users_controller.rb
    
  4. Check Rails.root is correct:
    Rails.root
    # => /Users/you/myapp
    

Detailed Troubleshooting: See Source Code Integration Documentation for 10+ specific scenarios and solutions.


Git Blame Not Working

Problem: Source code shows but no git blame information.

Quick Check:

git --version
# Should output: git version 2.x.x

Common Causes:

  1. Git not installed or not in PATH
  2. Not a git repository
  3. File not committed to git
  4. Git blame not enabled in config

Solutions:

  1. Enable git blame:
    config.enable_git_blame = true
    
  2. Verify git repository:
    git rev-parse --git-dir
    # Should output: .git
    
  3. Check file is committed:
    git log -- app/controllers/users_controller.rb
    # Should show commit history
    
  4. Test git blame manually:
    git blame -L 42,42 --porcelain app/controllers/users_controller.rb
    

Detailed Troubleshooting: See Source Code Integration Documentation


Problem: No “View on GitHub” button appearing.

Quick Check:

RailsErrorDashboard.configuration.git_repository_url
# Should return your repository URL

Common Causes:

  1. Repository URL not configured
  2. URL format incorrect (has .git suffix)
  3. Git branch strategy misconfigured

Solutions:

  1. Set repository URL:
    config.git_repository_url = "https://github.com/myorg/myapp"
    # Remove .git suffix if present!
    
  2. Choose branch strategy:
    config.git_branch_strategy = :current_branch  # or :commit_sha, :main
    
  3. Verify URL format (no .git):
    # ✅ Correct:
    "https://github.com/user/repo"
    "https://gitlab.com/user/repo"
    
    # ❌ Wrong:
    "https://github.com/user/repo.git"  # Remove .git!
    "git@github.com:user/repo.git"      # Use HTTPS format
    

Detailed Troubleshooting: See Source Code Integration Documentation


Permission Denied Errors

Problem: Getting “Permission denied” when reading source files.

Check Permissions:

ls -la app/controllers/users_controller.rb
# Should show: -rw-r--r-- or similar readable permissions

Solutions:

  1. Fix file permissions:
    chmod 644 app/controllers/**/*.rb
    
  2. Check Rails server user:
    ps aux | grep rails
    # Note which user is running Rails
    
  3. Ensure that user can read files:
    sudo -u rails-user cat app/controllers/users_controller.rb
    
  4. Docker users - check volume permissions:
    RUN chown -R app:app /app
    USER app
    

Dark Mode Styling Issues

Problem: Source code viewer not styled correctly in dark mode.

Solutions:

  1. Ensure you’re on v0.1.30+:
    bundle update rails_error_dashboard
    
  2. Clear browser cache:
    • Chrome/Firefox: Cmd+Shift+R (Mac) or Ctrl+F5 (Windows)
  3. Verify dark mode CSS loaded:
    // In browser console
    document.body.classList.contains('dark-mode')
    // Should return: true when dark mode is active
    

Performance Issues with Source Code

Problem: Error details page loads slowly with source code integration.

Quick Fixes:

  1. Reduce context lines:
    config.source_code_context_lines = 3  # Default: 5
    
  2. Increase cache TTL:
    config.source_code_cache_ttl = 7200  # 2 hours
    
  3. Disable git blame in production:
    if Rails.env.production?
      config.enable_git_blame = false  # Faster without git commands
    end
    
  4. Use Redis cache for better performance:
    # config/application.rb
    config.cache_store = :redis_cache_store, { url: ENV["REDIS_URL"] }
    

Caching Issues (Stale Code)

Problem: Seeing old/stale source code after making changes.

Quick Fix:

# In Rails console
Rails.cache.clear
# Or specifically:
Rails.cache.delete_matched("source_code/*")

Development Setup:

# Shorter cache in development
if Rails.env.development?
  config.source_code_cache_ttl = 60  # 1 minute instead of 1 hour
end

Complete Troubleshooting Guide

For comprehensive troubleshooting with 10+ scenarios, solutions, and examples, see: Source Code Integration Documentation - Troubleshooting Section

Includes solutions for:


Database Issues

Connection Pool Exhausted

Problem: “Could not obtain a connection from the pool” errors.

Solutions:

  1. Increase pool size:
    # config/database.yml
    production:
      pool: 20  # Instead of 5
    
  2. Use separate database with dedicated pool:
    config.use_separate_database = true
    config.database = :errors
    
    # config/database.yml
    errors:
      <<: *default
      database: errors_production
      pool: 10
    
  3. Check for connection leaks:
    # In rails console
    ActiveRecord::Base.connection_pool.stat
    # Shows: size, connections, busy, dead, idle, waiting
    

Slow Queries

Problem: Error dashboard queries taking >1 second.

Solutions:

  1. Verify indexes exist:
    -- PostgreSQL
    \d error_dashboard_error_logs
    # Should show multiple indexes
    
  2. Analyze slow queries:
    -- PostgreSQL
    EXPLAIN ANALYZE
    SELECT * FROM error_dashboard_error_logs
    WHERE occurred_at > NOW() - INTERVAL '7 days';
    
  3. Add composite indexes if missing:
    # Should already exist from migrations
    add_index :error_dashboard_error_logs, [:application_id, :occurred_at]
    add_index :error_dashboard_error_logs, [:hash_signature]
    

Multi-App Setup Problems

Errors from Wrong Application Appearing

Problem: Seeing errors from different apps in filtered view.

Solutions:

  1. Verify application names are unique:
    # In rails console
    RailsErrorDashboard::Application.pluck(:name)
    # Each should be unique
    
  2. Check application filter in UI:
    • Look for application dropdown in dashboard
    • Ensure correct app is selected
  3. Verify APP_NAME is set correctly:
    # Each app should have unique APP_NAME
    echo $APP_NAME
    # Should output: my-api, my-admin, etc.
    
  4. Check error application_id:
    error = RailsErrorDashboard::ErrorLog.last
    error.application.name
    # Should match expected app
    

Application Not Auto-Created

Problem: New application not appearing in dashboard.

Solutions:

  1. Check application_name configuration:
    RailsErrorDashboard.configuration.application_name
    # Should return app name
    
  2. Manually create application:
    # In rails console
    RailsErrorDashboard::Application.find_or_create_by_name("my-app")
    
  3. Verify auto-detection fallback:
    # Should use Rails.application name if not set
    Rails.application.class.module_parent_name
    

Debugging Techniques

Enable Internal Logging

See what Rails Error Dashboard is doing internally:

# config/initializers/rails_error_dashboard.rb
RailsErrorDashboard.configure do |config|
  config.enable_internal_logging = true
  config.log_level = :debug  # :debug, :info, :warn, :error, :silent
end

Restart server, then check logs:

tail -f log/development.log | grep "RailsErrorDashboard"

Test Error Logging Manually

# In rails console
begin
  raise "Manual test error"
rescue => e
  RailsErrorDashboard::Commands::LogError.call(
    exception: e,
    occurred_at: Time.current,
    platform: "test",
    severity: :high
  )
end

# Check if logged
RailsErrorDashboard::ErrorLog.last

Check Configuration Values

# In rails console
config = RailsErrorDashboard.configuration

# View all settings
config.instance_variables.each do |var|
  puts "#{var}: #{config.instance_variable_get(var).inspect}"
end

Verify Middleware Stack

# In rails console
Rails.application.config.middleware.to_a.each do |middleware|
  puts middleware.inspect
end

# Look for: RailsErrorDashboard::Middleware::ErrorCatcher

Test Notifications Directly

# Slack
RailsErrorDashboard::SlackNotificationJob.perform_now(error_log_id: 123)

# Email
RailsErrorDashboard::EmailNotificationJob.perform_now(error_log_id: 123)

# Discord
RailsErrorDashboard::DiscordNotificationJob.perform_now(error_log_id: 123)

Getting Help

If you’ve tried the solutions above and still have issues:

  1. Check GitHub Issues: Rails Error Dashboard Issues
  2. Search Discussions: GitHub Discussions
  3. Open New Issue: Include:
    • Rails version
    • Ruby version
    • Gem version
    • Error message (full backtrace)
    • Configuration (sanitize secrets!)
    • Steps to reproduce
  4. Security Issues: See SECURITY.md - DO NOT open public issue


Pro Tip: Enable internal logging (enable_internal_logging = true) when debugging issues. It reveals exactly what Rails Error Dashboard is doing internally.