Troubleshooting Guide
Comprehensive troubleshooting guide for Rails Error Dashboard. Solutions to common problems, error messages, and debugging techniques.
Table of Contents
- Installation & Setup Issues
- Configuration Problems
- Error Logging Issues
- Dashboard Access Problems
- Notification Issues
- Performance Problems
- Advanced Features Not Working
- Source Code Integration Issues
- Database Issues
- Multi-App Setup Problems
- Debugging Techniques
Installation & Setup Issues
Errors Not Being Logged After Installation
Symptoms: Dashboard is accessible but no errors appear.
Solutions:
- Verify middleware is installed:
# In rails console Rails.application.config.middleware.to_a.grep(/ErrorCatcher/) # Should return: [RailsErrorDashboard::Middleware::ErrorCatcher] - Check if middleware is enabled:
RailsErrorDashboard.configuration.enable_middleware # Should return: true - Manually trigger an error to test:
# In rails console raise "Test error from console" - Check Rails.error subscriber:
RailsErrorDashboard.configuration.enable_error_subscriber # Should return: true - 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:
- Check for existing tables:
rails db # Then: \dt error_dashboard* - Rollback and re-run:
rails db:rollback STEP=5 rails db:migrate - Drop and recreate (DEVELOPMENT ONLY):
rails db:drop db:create db:migrate - 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:
- Verify mount in routes:
rails routes | grep error_dashboard # Should show multiple routes - Check config/routes.rb:
# Should contain: mount RailsErrorDashboard::Engine => "/error_dashboard" - Restart server after adding mount:
rails server - 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:
- Restart server (required for initializer changes):
rails server - Check file location:
ls -la config/initializers/rails_error_dashboard.rb # File must exist in config/initializers/ - Check for syntax errors:
ruby -c config/initializers/rails_error_dashboard.rb # Should return: Syntax OK - 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:
- Verify variable is set:
echo $SLACK_WEBHOOK_URL # Should output the URL - Use dotenv-rails in development:
# Gemfile gem 'dotenv-rails', groups: [:development, :test]# .env file SLACK_WEBHOOK_URL=https://hooks.slack.com/services/... - Provide defaults in config:
config.slack_webhook_url = ENV.fetch('SLACK_WEBHOOK_URL', nil) - 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:
- 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! } - Test regex patterns:
# In rails console error_class = "ActiveRecord::RecordNotFound" /ActiveRecord::RecordNotFound/.match?(error_class) # Should return: true - 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:
- Check hash signature generation:
# In rails console error = RailsErrorDashboard::ErrorLog.last error.hash_signature # Should be consistent SHA-256 hash - 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 - 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:
- Ensure error subscriber is enabled:
config.enable_error_subscriber = true - Check job adapter error handling:
# Sidekiq example class YourJob < ApplicationJob retry_on StandardError, wait: :exponentially_longer def perform # Your code end end - 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:
- Check sampling rate:
RailsErrorDashboard.configuration.sampling_rate # 0.1 = 10%, 1.0 = 100% - Critical errors always logged (bypass sampling):
# Set error as critical to bypass sampling config.custom_severity_rules = { /Payment/ => :critical # Always logged } - Adjust rate based on volume:
# Start high, tune down config.sampling_rate = 0.5 # 50% - 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:
- Check credentials are set:
# In rails console RailsErrorDashboard.configuration.dashboard_username RailsErrorDashboard.configuration.dashboard_password # Should return configured values (not nil) - Verify HTTP Basic Auth header:
# Test with curl curl -u admin:password http://localhost:3000/error_dashboard # Should return 200, not 401 - Clear browser cache (old credentials may be cached):
- Chrome: Cmd+Shift+Delete → Clear browsing data
- Or use incognito window
- 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:
- Enable async logging:
config.async_logging = true - Add database indexes (should be automatic):
rails db:migrate:status | grep add_indexes # Should show "up" - Check for N+1 queries:
# Enable query logging in development # config/environments/development.rb config.active_record.verbose_query_logs = true - Reduce retention period:
config.retention_days = 30 # Instead of 90 - 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:
- Verify notifications are enabled:
# In rails console RailsErrorDashboard.configuration.enable_slack_notifications # Should return: true - Check webhook URL is set:
RailsErrorDashboard.configuration.slack_webhook_url # Should return your webhook URL - 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 - Check background jobs are running:
# Sidekiq ps aux | grep sidekiq # Solid Queue ps aux | grep solid_queue - 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 - 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:
- Check ActionMailer configuration:
# config/environments/production.rb config.action_mailer.delivery_method = :smtp config.action_mailer.smtp_settings = { address: "smtp.gmail.com", port: 587, # ... } - Verify email recipients are set:
RailsErrorDashboard.configuration.notification_email_recipients # Should return: ["team@example.com"] - Check email is enabled:
RailsErrorDashboard.configuration.enable_email_notifications # Should return: true - Test email delivery:
# In rails console TestMailer.test_email.deliver_now
Discord/PagerDuty Notifications Failing
Problem: Discord or PagerDuty webhooks not working.
Solutions:
- 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 - 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" } }' - 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:
- Configure retention policy:
config.retention_days = 30 # Auto-delete after 30 days - Manually clean old errors:
rails rails_error_dashboard:cleanup_old_errors - Limit backtrace lines:
config.max_backtrace_lines = 20 # Instead of 50 - Enable sampling:
config.sampling_rate = 0.1 # Log 10% of non-critical errors - Use separate database:
config.use_separate_database = true config.database = :errors
Background Jobs Queuing Up
Problem: Error logging jobs piling up in queue.
Solutions:
- Check job processor is running:
# Sidekiq bundle exec sidekiq # Solid Queue bin/jobs - Increase job concurrency:
# config/sidekiq.yml :concurrency: 10 # Instead of 5 - Monitor queue size:
# Sidekiq require 'sidekiq/api' Sidekiq::Queue.new.size # Solid Queue SolidQueue::Job.pending.count - 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:
- Check feature is enabled:
RailsErrorDashboard.configuration.enable_baseline_alerts # Should return: true - Verify minimum data exists:
- Need at least 7 days of error history
- Need at least 10 occurrences of an error type
- Check threshold settings:
config.baseline_alert_threshold_std_devs # Default: 2.0 (2 standard deviations) # Lower = more sensitive, Higher = less sensitive - Check cooldown period:
config.baseline_alert_cooldown_minutes # Default: 120 (2 hours between alerts for same error) - 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:
- Check feature is enabled:
RailsErrorDashboard.configuration.enable_similar_errors # Should return: true - Verify enough errors exist:
- Need at least 10 different error types
- Similarity requires variation in messages/backtraces
- Check similarity thresholds:
- Jaccard similarity: 70% match required
- Levenshtein distance: Calculated proportionally
- 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:
- Check feature is enabled:
RailsErrorDashboard.configuration.enable_platform_comparison # Should return: true - Verify platform data exists:
# In rails console RailsErrorDashboard::ErrorLog.pluck(:platform).uniq # Should return: ["iOS", "Android", "Web", etc.] - 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:
- Verify feature is enabled:
RailsErrorDashboard.configuration.enable_local_variables # Should return: true -
Check that the error was captured AFTER enabling — existing errors won’t have variables. Only new errors get variable data.
- 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:
-
Check Ruby version — requires Ruby 3.3+ for
TracePoint(:rescue). On Ruby < 3.3, the feature is auto-disabled. - Verify feature is enabled:
RailsErrorDashboard.configuration.detect_swallowed_exceptions # Should return: true -
Wait for flush interval — data is flushed to the database every
swallowed_exception_flush_intervalseconds (default: 60). Check back after a minute. - 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:
- Verify feature is enabled:
RailsErrorDashboard.configuration.enable_diagnostic_dump # Should return: true -
Try the rake task —
rails error_dashboard:diagnostic_dumpto verify the feature works outside the dashboard. - 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:
-
Check crash file path — look for JSON files in
Dir.tmpdir(or your customcrash_capture_path). -
Verify the crash was an unhandled exception —
at_exitonly captures when$!is set (an exception terminated the process). Clean exits viaexit(0)orSIGTERMdon’t trigger it. -
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:
- Feature not enabled in configuration
- File path is outside Rails.root
- Frame category is not
:app(gem frames don’t show source) - File doesn’t exist or isn’t readable
Solutions:
- Enable in initializer:
config.enable_source_code_integration = true -
Restart Rails server (required for initializer changes)
- Verify file exists and is readable:
ls -la app/controllers/users_controller.rb - 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:
- Git not installed or not in PATH
- Not a git repository
- File not committed to git
- Git blame not enabled in config
Solutions:
- Enable git blame:
config.enable_git_blame = true - Verify git repository:
git rev-parse --git-dir # Should output: .git - Check file is committed:
git log -- app/controllers/users_controller.rb # Should show commit history - Test git blame manually:
git blame -L 42,42 --porcelain app/controllers/users_controller.rb
Detailed Troubleshooting: See Source Code Integration Documentation
Repository Links Not Generating
Problem: No “View on GitHub” button appearing.
Quick Check:
RailsErrorDashboard.configuration.git_repository_url
# Should return your repository URL
Common Causes:
- Repository URL not configured
- URL format incorrect (has .git suffix)
- Git branch strategy misconfigured
Solutions:
- Set repository URL:
config.git_repository_url = "https://github.com/myorg/myapp" # Remove .git suffix if present! - Choose branch strategy:
config.git_branch_strategy = :current_branch # or :commit_sha, :main - 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:
- Fix file permissions:
chmod 644 app/controllers/**/*.rb - Check Rails server user:
ps aux | grep rails # Note which user is running Rails - Ensure that user can read files:
sudo -u rails-user cat app/controllers/users_controller.rb - 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:
- Ensure you’re on v0.1.30+:
bundle update rails_error_dashboard - Clear browser cache:
- Chrome/Firefox: Cmd+Shift+R (Mac) or Ctrl+F5 (Windows)
- 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:
- Reduce context lines:
config.source_code_context_lines = 3 # Default: 5 - Increase cache TTL:
config.source_code_cache_ttl = 7200 # 2 hours - Disable git blame in production:
if Rails.env.production? config.enable_git_blame = false # Faster without git commands end - 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:
- File not found errors
- Symlink issues
- Docker volume problems
- SELinux/AppArmor restrictions
- Git blame showing wrong author
- Configuration mistakes
- And more…
Database Issues
Connection Pool Exhausted
Problem: “Could not obtain a connection from the pool” errors.
Solutions:
- Increase pool size:
# config/database.yml production: pool: 20 # Instead of 5 - Use separate database with dedicated pool:
config.use_separate_database = true config.database = :errors# config/database.yml errors: <<: *default database: errors_production pool: 10 - 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:
- Verify indexes exist:
-- PostgreSQL \d error_dashboard_error_logs # Should show multiple indexes - Analyze slow queries:
-- PostgreSQL EXPLAIN ANALYZE SELECT * FROM error_dashboard_error_logs WHERE occurred_at > NOW() - INTERVAL '7 days'; - 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:
- Verify application names are unique:
# In rails console RailsErrorDashboard::Application.pluck(:name) # Each should be unique - Check application filter in UI:
- Look for application dropdown in dashboard
- Ensure correct app is selected
- Verify APP_NAME is set correctly:
# Each app should have unique APP_NAME echo $APP_NAME # Should output: my-api, my-admin, etc. - 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:
- Check application_name configuration:
RailsErrorDashboard.configuration.application_name # Should return app name - Manually create application:
# In rails console RailsErrorDashboard::Application.find_or_create_by_name("my-app") - 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:
- Check GitHub Issues: Rails Error Dashboard Issues
- Search Discussions: GitHub Discussions
- Open New Issue: Include:
- Rails version
- Ruby version
- Gem version
- Error message (full backtrace)
- Configuration (sanitize secrets!)
- Steps to reproduce
- Security Issues: See SECURITY.md - DO NOT open public issue
Related Documentation
- Configuration Guide - All configuration options
- Settings Dashboard - Verify current configuration
- API Reference - API endpoints and Ruby API
- QUICKSTART - Installation and setup
Pro Tip: Enable internal logging (enable_internal_logging = true) when debugging issues. It reveals exactly what Rails Error Dashboard is doing internally.