Error Reporting in Rails Applications

<!doctype html> <html dir="ltr" lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>Error Reporting in Rails Applications — Ruby on Rails Guides</title> <link rel="stylesheet" type="text/css" href="stylesheets/style-071e355820fc155a5c40ef8a1c0c4971.css" data-turbo-track="reload"> <link rel="stylesheet" type="text/css" href="stylesheets/print-a87ee66d50ce96bb83ac082f1249fe3e.css" media="print"> <link rel="stylesheet" type="text/css" href="stylesheets/highlight-a0d2133dd0073968b2d33b1f1360a2a3.css" data-turbo-track="reload"> <link rel="icon" href="images/favicon.ico" sizes="any"> <link rel="apple-touch-icon" href="images/icon.png"> <script src="javascripts/@hotwired--turbo-764f59c7edbeb902a9068c0340dd274e.js" data-turbo-track="reload"></script> <script src="javascripts/clipboard-8b7aed6f069f0cf58eeae353cd2f898b.js" data-turbo-track="reload"></script> <script src="javascripts/guides-897790ae3777ddd81bd4953f7ec99835.js" data-turbo-track="reload"></script> <meta property="og:title" content="Error Reporting in Rails Applications — Ruby on Rails Guides" /> <meta name="description" content="Error Reporting in Rails ApplicationsThis guide introduces ways to manage errors in a Rails application.After reading this guide, you will know: How to use Rails' error reporter to capture and report errors. How to create custom subscribers for your error-reporting service." /> <meta property="og:description" content="Error Reporting in Rails ApplicationsThis guide introduces ways to manage errors in a Rails application.After reading this guide, you will know: How to use Rails' error reporter to capture and report errors. How to create custom subscribers for your error-reporting service." /> <meta property="og:locale" content="en_US" /> <meta property="og:site_name" content="Ruby on Rails Guides" /> <meta property="og:image" content="https://avatars.githubusercontent.com/u/4223" /> <meta property="og:type" content="website" /> <link rel="preconnect" href="https://fonts.googleapis.com"> <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin> <link href="https://fonts.googleapis.com/css2?family=Noto+Sans+Arabic:wght@100..900&display=swap" rel="stylesheet"> <link href="https://fonts.googleapis.com/css2?family=Heebo:wght@100..900&family=Noto+Sans+Arabic:wght@100..900&display=swap" rel="stylesheet"> <meta name="theme-color" content="#C81418"> </head> <body dir="ltr" class="guide no-js"> <script> document.body.classList.remove('no-js') </script> <a id="main-skip-link" href="#main" class="skip-link" data-turbo="false"> Skip to main content </a> <div id="mobile-navigation-bar"> <div class="wrapper"> <strong class="more-info-label">More at <a href="https://rubyonrails.org/">rubyonrails.org:</a> </strong> <button type="button" class="js-only red-button more-info-button" id="more-info" aria-controls="more-info-links" aria-expanded="false"> More Ruby on Rails </button> <ul id="more-info-links" class="more-info-links hidden"> <li class="more-info"><a href="https://rubyonrails.org/blog">Blog</a></li> <li class="more-info"><a href="https://guides.rubyonrails.org/">Guides</a></li> <li class="more-info"><a href="https://api.rubyonrails.org/">API</a></li> <li class="more-info"><a href="https://discuss.rubyonrails.org/">Forum</a></li> <li class="more-info"><a href="https://github.com/rails/rails">Contribute on GitHub</a></li> </ul> </div> </div> <header id="page-header"> <div class="wrapper clearfix"> <nav id="feature-nav"> <div class="header-logo"> <a href="index.html" title="Guides home for v8.0.0 Guides">Guides</a> <span id="version-switcher" class="js-only"> <label for="version-switcher-select">Version: <span class="visibly-hidden">pick from the list to go to that Rails version's guides</span></label> <select id="version-switcher-select" class="guides-version"> <option value="https://edgeguides.rubyonrails.org/">Edge</option> <option value="https://guides.rubyonrails.org/v8.0/" selected>8.0</option> <option value="https://guides.rubyonrails.org/v7.2/">7.2</option> <option value="https://guides.rubyonrails.org/v7.1/">7.1</option> <option value="https://guides.rubyonrails.org/v7.0/">7.0</option> <option value="https://guides.rubyonrails.org/v6.1/">6.1</option> <option value="https://guides.rubyonrails.org/v6.0/">6.0</option> <option value="https://guides.rubyonrails.org/v5.2/">5.2</option> <option value="https://guides.rubyonrails.org/v5.1/">5.1</option> <option value="https://guides.rubyonrails.org/v5.0/">5.0</option> <option value="https://guides.rubyonrails.org/v4.2/">4.2</option> <option value="https://guides.rubyonrails.org/v4.1/">4.1</option> <option value="https://guides.rubyonrails.org/v4.0/">4.0</option> <option value="https://guides.rubyonrails.org/v3.2/">3.2</option> <option value="https://guides.rubyonrails.org/v3.1/">3.1</option> <option value="https://guides.rubyonrails.org/v3.0/">3.0</option> <option value="https://guides.rubyonrails.org/v2.3/">2.3</option> </select> </span> </div> <ul class="nav"> <li><a class="nav-item" id="home_nav" href="https://rubyonrails.org/">Home</a></li> <li class="guides-index guides-index-large"> <a href="index.html" id="guides-menu-button" data-aria-controls="guides" data-aria-expanded="false" class="guides-index-item nav-item">Guides Index</a> <div id="guides" class="clearfix" style="display: none;"> <hr /> <dl class="guides-section-container"> <div class="guides-section"> <dt>Start Here</dt> <dd><a href="getting_started.html">Getting Started with Rails</a></dd> </div> <div class="guides-section"> <dt>Models</dt> <dd><a href="active_record_basics.html">Active Record Basics</a></dd> <dd><a href="active_record_migrations.html">Active Record Migrations</a></dd> <dd><a href="active_record_validations.html">Active Record Validations</a></dd> <dd><a href="active_record_callbacks.html">Active Record Callbacks</a></dd> <dd><a href="association_basics.html">Active Record Associations</a></dd> <dd><a href="active_record_querying.html">Active Record Query Interface</a></dd> <dd><a href="active_model_basics.html">Active Model Basics</a></dd> </div> <div class="guides-section"> <dt>Views</dt> <dd><a href="action_view_overview.html">Action View Overview</a></dd> <dd><a href="layouts_and_rendering.html">Layouts and Rendering in Rails</a></dd> <dd><a href="action_view_helpers.html">Action View Helpers</a></dd> <dd><a href="form_helpers.html">Action View Form Helpers</a></dd> </div> <div class="guides-section"> <dt>Controllers</dt> <dd><a href="action_controller_overview.html">Action Controller Overview</a></dd> <dd><a href="routing.html">Rails Routing from the Outside In</a></dd> </div> <div class="guides-section"> <dt>Other Components</dt> <dd><a href="active_support_core_extensions.html">Active Support Core Extensions</a></dd> <dd><a href="action_mailer_basics.html">Action Mailer Basics</a></dd> <dd><a href="action_mailbox_basics.html">Action Mailbox Basics</a></dd> <dd><a href="action_text_overview.html">Action Text Overview</a></dd> <dd><a href="active_job_basics.html">Active Job Basics</a></dd> <dd><a href="active_storage_overview.html">Active Storage Overview</a></dd> <dd><a href="action_cable_overview.html">Action Cable Overview</a></dd> </div> <div class="guides-section"> <dt>Digging Deeper</dt> <dd><a href="i18n.html">Rails Internationalization (I18n) API</a></dd> <dd><a href="testing.html">Testing Rails Applications</a></dd> <dd><a href="security.html">Securing Rails Applications</a></dd> <dd><a href="error_reporting.html">Error Reporting in Rails Applications</a></dd> <dd><a href="debugging_rails_applications.html">Debugging Rails Applications</a></dd> <dd><a href="configuring.html">Configuring Rails Applications</a></dd> <dd><a href="command_line.html">The Rails Command Line</a></dd> <dd><a href="asset_pipeline.html">The Asset Pipeline</a></dd> <dd><a href="working_with_javascript_in_rails.html">Working with JavaScript in Rails</a></dd> <dd><a href="autoloading_and_reloading_constants.html">Autoloading and Reloading</a></dd> <dd><a href="caching_with_rails.html">Caching with Rails: An Overview</a></dd> <dd><a href="api_app.html">Using Rails for API-only Applications</a></dd> <dd><a href="tuning_performance_for_deployment.html">Tuning Performance for Deployment</a></dd> </div> <div class="guides-section"> <dt>Advanced Active Record</dt> <dd><a href="active_record_multiple_databases.html">Multiple Databases</a></dd> <dd><a href="active_record_composite_primary_keys.html">Composite Primary Keys</a></dd> </div> <div class="guides-section"> <dt>Extending Rails</dt> <dd><a href="rails_on_rack.html">Rails on Rack</a></dd> <dd><a href="generators.html">Creating and Customizing Rails Generators & Templates</a></dd> </div> <div class="guides-section"> <dt>Contributing</dt> <dd><a href="contributing_to_ruby_on_rails.html">Contributing to Ruby on Rails</a></dd> <dd><a href="api_documentation_guidelines.html">API Documentation Guidelines</a></dd> <dd><a href="ruby_on_rails_guides_guidelines.html">Guides Guidelines</a></dd> <dd><a href="development_dependencies_install.html">Installing Rails Core Development Dependencies</a></dd> </div> <div class="guides-section"> <dt>Policies</dt> <dd><a href="maintenance_policy.html">Maintenance Policy</a></dd> </div> <div class="guides-section"> <dt>Release Notes</dt> <dd><a href="upgrading_ruby_on_rails.html">Upgrading Ruby on Rails</a></dd> <dd><a href="7_2_release_notes.html">Version 7.2 - August 2024</a></dd> <dd><a href="7_1_release_notes.html">Version 7.1 - October 2023</a></dd> <dd><a href="7_0_release_notes.html">Version 7.0 - December 2021</a></dd> <dd><a href="6_1_release_notes.html">Version 6.1 - December 2020</a></dd> <dd><a href="6_0_release_notes.html">Version 6.0 - August 2019</a></dd> <dd><a href="5_2_release_notes.html">Version 5.2 - April 2018</a></dd> <dd><a href="5_1_release_notes.html">Version 5.1 - April 2017</a></dd> <dd><a href="5_0_release_notes.html">Version 5.0 - June 2016</a></dd> <dd><a href="4_2_release_notes.html">Version 4.2 - December 2014</a></dd> <dd><a href="4_1_release_notes.html">Version 4.1 - April 2014</a></dd> <dd><a href="4_0_release_notes.html">Version 4.0 - June 2013</a></dd> <dd><a href="3_2_release_notes.html">Version 3.2 - January 2012</a></dd> <dd><a href="3_1_release_notes.html">Version 3.1 - August 2011</a></dd> <dd><a href="3_0_release_notes.html">Version 3.0 - August 2010</a></dd> <dd><a href="2_3_release_notes.html">Version 2.3 - March 2009</a></dd> <dd><a href="2_2_release_notes.html">Version 2.2 - November 2008</a></dd> </div> </dl> </div> </li> <li><a class="nav-item" href="contributing_to_ruby_on_rails.html">Contribute</a></li> <li class="guides-index guides-index-small js-only"> <label for="guides-selector"> Navigate to a guide: </label> <select id="guides-selector" class="guides-index-item nav-item"> <option value="index.html">Guides Index</option> <optgroup label="Start Here"> <option value="getting_started.html">Getting Started with Rails</option> </optgroup> <optgroup label="Models"> <option value="active_record_basics.html">Active Record Basics</option> <option value="active_record_migrations.html">Active Record Migrations</option> <option value="active_record_validations.html">Active Record Validations</option> <option value="active_record_callbacks.html">Active Record Callbacks</option> <option value="association_basics.html">Active Record Associations</option> <option value="active_record_querying.html">Active Record Query Interface</option> <option value="active_model_basics.html">Active Model Basics</option> </optgroup> <optgroup label="Views"> <option value="action_view_overview.html">Action View Overview</option> <option value="layouts_and_rendering.html">Layouts and Rendering in Rails</option> <option value="action_view_helpers.html">Action View Helpers</option> <option value="form_helpers.html">Action View Form Helpers</option> </optgroup> <optgroup label="Controllers"> <option value="action_controller_overview.html">Action Controller Overview</option> <option value="routing.html">Rails Routing from the Outside In</option> </optgroup> <optgroup label="Other Components"> <option value="active_support_core_extensions.html">Active Support Core Extensions</option> <option value="action_mailer_basics.html">Action Mailer Basics</option> <option value="action_mailbox_basics.html">Action Mailbox Basics</option> <option value="action_text_overview.html">Action Text Overview</option> <option value="active_job_basics.html">Active Job Basics</option> <option value="active_storage_overview.html">Active Storage Overview</option> <option value="action_cable_overview.html">Action Cable Overview</option> </optgroup> <optgroup label="Digging Deeper"> <option value="i18n.html">Rails Internationalization (I18n) API</option> <option value="testing.html">Testing Rails Applications</option> <option value="security.html">Securing Rails Applications</option> <option value="error_reporting.html">Error Reporting in Rails Applications</option> <option value="debugging_rails_applications.html">Debugging Rails Applications</option> <option value="configuring.html">Configuring Rails Applications</option> <option value="command_line.html">The Rails Command Line</option> <option value="asset_pipeline.html">The Asset Pipeline</option> <option value="working_with_javascript_in_rails.html">Working with JavaScript in Rails</option> <option value="autoloading_and_reloading_constants.html">Autoloading and Reloading</option> <option value="caching_with_rails.html">Caching with Rails: An Overview</option> <option value="api_app.html">Using Rails for API-only Applications</option> <option value="tuning_performance_for_deployment.html">Tuning Performance for Deployment</option> </optgroup> <optgroup label="Advanced Active Record"> <option value="active_record_multiple_databases.html">Multiple Databases</option> <option value="active_record_composite_primary_keys.html">Composite Primary Keys</option> </optgroup> <optgroup label="Extending Rails"> <option value="rails_on_rack.html">Rails on Rack</option> <option value="generators.html">Creating and Customizing Rails Generators & Templates</option> </optgroup> <optgroup label="Contributing"> <option value="contributing_to_ruby_on_rails.html">Contributing to Ruby on Rails</option> <option value="api_documentation_guidelines.html">API Documentation Guidelines</option> <option value="ruby_on_rails_guides_guidelines.html">Guides Guidelines</option> <option value="development_dependencies_install.html">Installing Rails Core Development Dependencies</option> </optgroup> <optgroup label="Policies"> <option value="maintenance_policy.html">Maintenance Policy</option> </optgroup> <optgroup label="Release Notes"> <option value="upgrading_ruby_on_rails.html">Upgrading Ruby on Rails</option> <option value="7_2_release_notes.html">Version 7.2 - August 2024</option> <option value="7_1_release_notes.html">Version 7.1 - October 2023</option> <option value="7_0_release_notes.html">Version 7.0 - December 2021</option> <option value="6_1_release_notes.html">Version 6.1 - December 2020</option> <option value="6_0_release_notes.html">Version 6.0 - August 2019</option> <option value="5_2_release_notes.html">Version 5.2 - April 2018</option> <option value="5_1_release_notes.html">Version 5.1 - April 2017</option> <option value="5_0_release_notes.html">Version 5.0 - June 2016</option> <option value="4_2_release_notes.html">Version 4.2 - December 2014</option> <option value="4_1_release_notes.html">Version 4.1 - April 2014</option> <option value="4_0_release_notes.html">Version 4.0 - June 2013</option> <option value="3_2_release_notes.html">Version 3.2 - January 2012</option> <option value="3_1_release_notes.html">Version 3.1 - August 2011</option> <option value="3_0_release_notes.html">Version 3.0 - August 2010</option> <option value="2_3_release_notes.html">Version 2.3 - March 2009</option> <option value="2_2_release_notes.html">Version 2.2 - November 2008</option> </optgroup> </select> </li> </ul> </nav> </div> </header> <hr class="hide" /> <main id="main"> <article> <header id="feature"> <div class="wrapper"> <h1>Error Reporting in Rails Applications</h1><p>This guide introduces ways to manage errors in a Rails application.</p><p>After reading this guide, you will know:</p> <ul> <li>How to use Rails' error reporter to capture and report errors.</li> <li>How to create custom subscribers for your error-reporting service.</li> </ul> <nav id="column-side" aria-label="Chapter" class="guide-index" data-turbo="false"> <a id="chapter-nav-skip-link" href="#article-body" class="skip-link"> Skip to article body </a> <h2 class="chapter"> <picture aria-hidden="true">  <source srcset="images/icon_book-close-bookmark-1-wht.svg" media="(prefers-color-scheme: dark)" /> <img src="images/icon_book-close-bookmark-1.svg" alt="Chapter Icon" /> </picture> Chapters </h2> <ol class="chapters"> <li><a href="#error-reporting">Error Reporting</a> <ul> <li><a href="#subscribing-to-the-reporter">Subscribing to the Reporter</a></li> <li><a href="#using-the-error-reporter">Using the Error Reporter</a></li> <li><a href="#error-reporting-options">Error-reporting Options</a></li> <li><a href="#setting-context-globally">Setting Context Globally</a></li> <li><a href="#filtering-by-error-classes">Filtering by Error Classes</a></li> <li><a href="#disabling-notifications">Disabling Notifications</a></li> </ul></li> <li><a href="#error-reporting-libraries">Error-reporting Libraries</a></li> </ol> </nav> </div> </header> <div class="wrapper"> <div id="column-main"> <section id="article-body"> <h2 id="error-reporting"><a class="anchorlink" href="#error-reporting" data-turbo="false"><span>1</span> Error Reporting</a></h2><p>The Rails <a href="https://api.rubyonrails.org/v8.0.0/classes/ActiveSupport/ErrorReporter.html">error reporter</a> provides a standard way to collect errors that occur in your application and report them to your preferred service or location (e.g. you could report the errors to a monitoring service such as Sentry).</p><p>It aims to replace boilerplate error-handling code like this:</p><div class="interstitial code"> <pre><code class="highlight ruby"><span class="k">begin</span> <span class="n">do_something</span> <span class="k">rescue</span> <span class="no">SomethingIsBroken</span> <span class="o">=></span> <span class="n">error</span> <span class="no">MyErrorReportingService</span><span class="p">.</span><span class="nf">notify</span><span class="p">(</span><span class="n">error</span><span class="p">)</span> <span class="k">end</span> </code></pre> <button class="clipboard-button" data-clipboard-text="begin do_something rescue SomethingIsBroken => error MyErrorReportingService.notify(error) end ">Copy</button> </div> <p>with a consistent interface:</p><div class="interstitial code"> <pre><code class="highlight ruby"><span class="no">Rails</span><span class="p">.</span><span class="nf">error</span><span class="p">.</span><span class="nf">handle</span><span class="p">(</span><span class="no">SomethingIsBroken</span><span class="p">)</span> <span class="k">do</span> <span class="n">do_something</span> <span class="k">end</span> </code></pre> <button class="clipboard-button" data-clipboard-text="Rails.error.handle(SomethingIsBroken) do do_something end ">Copy</button> </div> <p>Rails wraps all executions (such as HTTP requests, <a href="active_job_basics.html">jobs</a>, and <a href="command_line.html#bin-rails-runner">rails runner</a> invocations) in the error reporter, so any unhandled errors raised in your app will automatically be reported to your error-reporting service via their subscribers.</p><p>This means that third-party error-reporting libraries no longer need to insert a <a href="rails_on_rack.html">Rack</a> middleware or do any monkey-patching to capture unhandled errors. Libraries that use <a href="https://api.rubyonrails.org/v8.0.0/classes/ActiveSupport.html">Active Support</a> can also use this to non-intrusively report warnings that would previously have been lost in logs.</p><div class="interstitial note"><p>Using the Rails error reporter is optional, as other means of capturing errors still work.</p></div><h3 id="subscribing-to-the-reporter"><a class="anchorlink" href="#subscribing-to-the-reporter" data-turbo="false"><span>1.1</span> Subscribing to the Reporter</a></h3><p>To use the error reporter with an external service, you need a <em>subscriber</em>. A subscriber can be any Ruby object with a <code>report</code> method. When an error occurs in your application or is manually reported, the Rails error reporter will call this method with the error object and some options.</p><div class="interstitial note"><p>Some error-reporting libraries, such as Sentry's and Honeybadger's, automatically register a subscriber for you.</p></div><p>You may also create a custom subscriber. For example:</p><div class="interstitial code"> <pre><code class="highlight ruby"><span class="c1"># config/initializers/error_subscriber.rb</span> <span class="k">class</span> <span class="nc">ErrorSubscriber</span> <span class="k">def</span> <span class="nf">report</span><span class="p">(</span><span class="n">error</span><span class="p">,</span> <span class="n">handled</span><span class="p">:,</span> <span class="n">severity</span><span class="p">:,</span> <span class="n">context</span><span class="p">:,</span> <span class="ss">source: </span><span class="kp">nil</span><span class="p">)</span> <span class="no">MyErrorReportingService</span><span class="p">.</span><span class="nf">report_error</span><span class="p">(</span><span class="n">error</span><span class="p">,</span> <span class="ss">context: </span><span class="n">context</span><span class="p">,</span> <span class="ss">handled: </span><span class="n">handled</span><span class="p">,</span> <span class="ss">level: </span><span class="n">severity</span><span class="p">)</span> <span class="k">end</span> <span class="k">end</span> </code></pre> <button class="clipboard-button" data-clipboard-text="class ErrorSubscriber def report(error, handled:, severity:, context:, source: nil) MyErrorReportingService.report_error(error, context: context, handled: handled, level: severity) end end ">Copy</button> </div> <p>After defining the subscriber class, you can register it by calling the <a href="https://api.rubyonrails.org/v8.0.0/classes/ActiveSupport/ErrorReporter.html#method-i-subscribe"><code>Rails.error.subscribe</code></a> method:</p><div class="interstitial code"> <pre><code class="highlight ruby"><span class="no">Rails</span><span class="p">.</span><span class="nf">error</span><span class="p">.</span><span class="nf">subscribe</span><span class="p">(</span><span class="no">ErrorSubscriber</span><span class="p">.</span><span class="nf">new</span><span class="p">)</span> </code></pre> <button class="clipboard-button" data-clipboard-text="Rails.error.subscribe(ErrorSubscriber.new) ">Copy</button> </div> <p>You can register as many subscribers as you wish. Rails will call them in the order in which they were registered.</p><p>It is also possible to unregister a subscriber by calling <a href="https://api.rubyonrails.org/v8.0.0/classes/ActiveSupport/ErrorReporter.html#method-i-unsubscribe"><code>Rails.error.unsubscribe</code></a>. This may be useful if you'd like to replace or remove a subscriber added by one of your dependencies. Both <code>subscribe</code> and <code>unsubscribe</code> can take either a subscriber or a class as follows:</p><div class="interstitial code"> <pre><code class="highlight ruby"><span class="n">subscriber</span> <span class="o">=</span> <span class="no">ErrorSubscriber</span><span class="p">.</span><span class="nf">new</span> <span class="no">Rails</span><span class="p">.</span><span class="nf">error</span><span class="p">.</span><span class="nf">unsubscribe</span><span class="p">(</span><span class="n">subscriber</span><span class="p">)</span> <span class="c1"># or</span> <span class="no">Rails</span><span class="p">.</span><span class="nf">error</span><span class="p">.</span><span class="nf">unsubscribe</span><span class="p">(</span><span class="no">ErrorSubscriber</span><span class="p">)</span> </code></pre> <button class="clipboard-button" data-clipboard-text="subscriber = ErrorSubscriber.new Rails.error.unsubscribe(subscriber) # or Rails.error.unsubscribe(ErrorSubscriber) ">Copy</button> </div> <div class="interstitial note"><p>The Rails error reporter will always call registered subscribers, regardless of your environment. However, many error-reporting services only report errors in production by default. You should configure and test your setup across environments as needed.</p></div><h3 id="using-the-error-reporter"><a class="anchorlink" href="#using-the-error-reporter" data-turbo="false"><span>1.2</span> Using the Error Reporter</a></h3><p>Rails error reporter has four methods that allow you to report methods in different ways:</p> <ul> <li><code>Rails.error.handle</code></li> <li><code>Rails.error.record</code></li> <li><code>Rails.error.report</code></li> <li><code>Rails.error.unexpected</code></li> </ul> <h4 id="reporting-and-swallowing-errors"><a class="anchorlink" href="#reporting-and-swallowing-errors" data-turbo="false"><span>1.2.1</span> Reporting and Swallowing Errors</a></h4><p>The <a href="https://api.rubyonrails.org/v8.0.0/classes/ActiveSupport/ErrorReporter.html#method-i-handle"><code>Rails.error.handle</code></a> method will report any error raised within the block. It will then <strong>swallow</strong> the error, and the rest of your code outside the block will continue as normal.</p><div class="interstitial code"> <pre><code class="highlight ruby"><span class="n">result</span> <span class="o">=</span> <span class="no">Rails</span><span class="p">.</span><span class="nf">error</span><span class="p">.</span><span class="nf">handle</span> <span class="k">do</span> <span class="mi">1</span> <span class="o">+</span> <span class="s2">"1"</span> <span class="c1"># raises TypeError</span> <span class="k">end</span> <span class="n">result</span> <span class="c1"># => nil</span> <span class="mi">1</span> <span class="o">+</span> <span class="mi">1</span> <span class="c1"># This will be executed</span> </code></pre> <button class="clipboard-button" data-clipboard-text="result = Rails.error.handle do 1 + "1" # raises TypeError end result # => nil 1 + 1 # This will be executed ">Copy</button> </div> <p>If no error is raised in the block, <code>Rails.error.handle</code> will return the result of the block, otherwise it will return <code>nil</code>. You can override this by providing a <code>fallback</code>:</p><div class="interstitial code"> <pre><code class="highlight ruby"><span class="n">user</span> <span class="o">=</span> <span class="no">Rails</span><span class="p">.</span><span class="nf">error</span><span class="p">.</span><span class="nf">handle</span><span class="p">(</span><span class="ss">fallback: </span><span class="o">-></span> <span class="p">{</span> <span class="no">User</span><span class="p">.</span><span class="nf">anonymous</span> <span class="p">})</span> <span class="k">do</span> <span class="no">User</span><span class="p">.</span><span class="nf">find</span><span class="p">(</span><span class="n">params</span><span class="p">[</span><span class="ss">:id</span><span class="p">])</span> <span class="k">end</span> </code></pre> <button class="clipboard-button" data-clipboard-text="user = Rails.error.handle(fallback: -> { User.anonymous }) do User.find(params[:id]) end ">Copy</button> </div> <h4 id="reporting-and-re-raising-errors"><a class="anchorlink" href="#reporting-and-re-raising-errors" data-turbo="false"><span>1.2.2</span> Reporting and Re-raising Errors</a></h4><p>The <a href="https://api.rubyonrails.org/v8.0.0/classes/ActiveSupport/ErrorReporter.html#method-i-record"><code>Rails.error.record</code></a> method will report errors to all registered subscribers and then <strong>re-raise</strong> the error, meaning that the rest of your code won't execute.</p><div class="interstitial code"> <pre><code class="highlight ruby"><span class="no">Rails</span><span class="p">.</span><span class="nf">error</span><span class="p">.</span><span class="nf">record</span> <span class="k">do</span> <span class="mi">1</span> <span class="o">+</span> <span class="s2">"1"</span> <span class="c1"># raises TypeError</span> <span class="k">end</span> <span class="mi">1</span> <span class="o">+</span> <span class="mi">1</span> <span class="c1"># This won't be executed</span> </code></pre> <button class="clipboard-button" data-clipboard-text="Rails.error.record do 1 + "1" # raises TypeError end 1 + 1 # This won't be executed ">Copy</button> </div> <p>If no error is raised in the block, <code>Rails.error.record</code> will return the result of the block.</p><h4 id="manually-reporting-errors"><a class="anchorlink" href="#manually-reporting-errors" data-turbo="false"><span>1.2.3</span> Manually Reporting Errors</a></h4><p>You can also manually report errors by calling <a href="https://api.rubyonrails.org/v8.0.0/classes/ActiveSupport/ErrorReporter.html#method-i-report"><code>Rails.error.report</code></a>:</p><div class="interstitial code"> <pre><code class="highlight ruby"><span class="k">begin</span> <span class="c1"># code</span> <span class="k">rescue</span> <span class="no">StandardError</span> <span class="o">=></span> <span class="n">e</span> <span class="no">Rails</span><span class="p">.</span><span class="nf">error</span><span class="p">.</span><span class="nf">report</span><span class="p">(</span><span class="n">e</span><span class="p">)</span> <span class="k">end</span> </code></pre> <button class="clipboard-button" data-clipboard-text="begin # code rescue StandardError => e Rails.error.report(e) end ">Copy</button> </div> <p>Any options you pass will be passed on to the error subscribers.</p><h4 id="reporting-unexpected-errors"><a class="anchorlink" href="#reporting-unexpected-errors" data-turbo="false"><span>1.2.4</span> Reporting Unexpected Errors</a></h4><p>You can report any unexpected error by calling <a href="https://api.rubyonrails.org/v8.0.0/classes/ActiveSupport/ErrorReporter.html#method-i-unexpected" "=""><code>Rails.error.unexpected</code></a>.</p><p>When called in production, this method will return nil after the error is reported and the execution of your code will continue.</p><p>When called in development, the error will be wrapped in a new error class (to ensure it's not being rescued higher in the stack) and surfaced to the developer for debugging.</p><p>For example:</p><div class="interstitial code"> <pre><code class="highlight ruby"><span class="k">def</span> <span class="nf">edit</span> <span class="k">if</span> <span class="n">published?</span> <span class="no">Rails</span><span class="p">.</span><span class="nf">error</span><span class="p">.</span><span class="nf">unexpected</span><span class="p">(</span><span class="s2">"[BUG] Attempting to edit a published article, that shouldn't be possible"</span><span class="p">)</span> <span class="kp">false</span> <span class="k">end</span> <span class="c1"># ...</span> <span class="k">end</span> </code></pre> <button class="clipboard-button" data-clipboard-text="def edit if published? Rails.error.unexpected("[BUG] Attempting to edit a published article, that shouldn't be possible") false end # ... end ">Copy</button> </div> <div class="interstitial note"><p>This method is intended to gracefully handle any errors that may occur in production, but that aren't anticipated to be the result of typical use.</p></div><h3 id="error-reporting-options"><a class="anchorlink" href="#error-reporting-options" data-turbo="false"><span>1.3</span> Error-reporting Options</a></h3><p>The reporting APIs <code>#handle</code>, <code>#record</code>, and <code>#report</code> support the following options, which are then passed along to all registered subscribers:</p> <ul> <li><code>handled</code>: a <code>Boolean</code> to indicate if the error was handled. This is set to <code>true</code> by default. <code>#record</code> sets this to <code>false</code>.</li> <li><code>severity</code>: a <code>Symbol</code> describing the severity of the error. Expected values are: <code>:error</code>, <code>:warning</code>, and <code>:info</code>. <code>#handle</code> sets this to <code>:warning</code>, while <code>#record</code> sets it to <code>:error</code>.</li> <li><code>context</code>: a <code>Hash</code> to provide more context about the error, like request or user details</li> <li><code>source</code>: a <code>String</code> about the source of the error. The default source is <code>"application"</code>. Errors reported by internal libraries may set other sources; the Redis cache library may use <code>"redis_cache_store.active_support"</code>, for instance. Your subscriber can use the source to ignore errors you aren't interested in.</li> </ul> <div class="interstitial code"> <pre><code class="highlight ruby"><span class="no">Rails</span><span class="p">.</span><span class="nf">error</span><span class="p">.</span><span class="nf">handle</span><span class="p">(</span><span class="ss">context: </span><span class="p">{</span> <span class="ss">user_id: </span><span class="n">user</span><span class="p">.</span><span class="nf">id</span> <span class="p">},</span> <span class="ss">severity: :info</span><span class="p">)</span> <span class="k">do</span> <span class="c1"># ...</span> <span class="k">end</span> </code></pre> <button class="clipboard-button" data-clipboard-text="Rails.error.handle(context: { user_id: user.id }, severity: :info) do # ... end ">Copy</button> </div> <h3 id="setting-context-globally"><a class="anchorlink" href="#setting-context-globally" data-turbo="false"><span>1.4</span> Setting Context Globally</a></h3><p>In addition to setting context through the <code>context</code> option, you can use <a href="https://api.rubyonrails.org/v8.0.0/classes/ActiveSupport/ErrorReporter.html#method-i-set_context"><code>Rails.error.set_context</code></a>. For example:</p><div class="interstitial code"> <pre><code class="highlight ruby"><span class="no">Rails</span><span class="p">.</span><span class="nf">error</span><span class="p">.</span><span class="nf">set_context</span><span class="p">(</span><span class="ss">section: </span><span class="s2">"checkout"</span><span class="p">,</span> <span class="ss">user_id: </span><span class="vi">@user</span><span class="p">.</span><span class="nf">id</span><span class="p">)</span> </code></pre> <button class="clipboard-button" data-clipboard-text="Rails.error.set_context(section: "checkout", user_id: @user.id) ">Copy</button> </div> <p>Any context set this way will be merged with the <code>context</code> option</p><div class="interstitial code"> <pre><code class="highlight ruby"><span class="no">Rails</span><span class="p">.</span><span class="nf">error</span><span class="p">.</span><span class="nf">set_context</span><span class="p">(</span><span class="ss">a: </span><span class="mi">1</span><span class="p">)</span> <span class="no">Rails</span><span class="p">.</span><span class="nf">error</span><span class="p">.</span><span class="nf">handle</span><span class="p">(</span><span class="ss">context: </span><span class="p">{</span> <span class="ss">b: </span><span class="mi">2</span> <span class="p">})</span> <span class="p">{</span> <span class="k">raise</span> <span class="p">}</span> <span class="c1"># The reported context will be: {:a=>1, :b=>2}</span> <span class="no">Rails</span><span class="p">.</span><span class="nf">error</span><span class="p">.</span><span class="nf">handle</span><span class="p">(</span><span class="ss">context: </span><span class="p">{</span> <span class="ss">b: </span><span class="mi">3</span> <span class="p">})</span> <span class="p">{</span> <span class="k">raise</span> <span class="p">}</span> <span class="c1"># The reported context will be: {:a=>1, :b=>3}</span> </code></pre> <button class="clipboard-button" data-clipboard-text="Rails.error.set_context(a: 1) Rails.error.handle(context: { b: 2 }) { raise } # The reported context will be: {:a=>1, :b=>2} Rails.error.handle(context: { b: 3 }) { raise } # The reported context will be: {:a=>1, :b=>3} ">Copy</button> </div> <h3 id="filtering-by-error-classes"><a class="anchorlink" href="#filtering-by-error-classes" data-turbo="false"><span>1.5</span> Filtering by Error Classes</a></h3><p>With <code>Rails.error.handle</code> and <code>Rails.error.record</code>, you can also choose to only report errors of certain classes. For example:</p><div class="interstitial code"> <pre><code class="highlight ruby"><span class="no">Rails</span><span class="p">.</span><span class="nf">error</span><span class="p">.</span><span class="nf">handle</span><span class="p">(</span><span class="no">IOError</span><span class="p">)</span> <span class="k">do</span> <span class="mi">1</span> <span class="o">+</span> <span class="s2">"1"</span> <span class="c1"># raises TypeError</span> <span class="k">end</span> <span class="mi">1</span> <span class="o">+</span> <span class="mi">1</span> <span class="c1"># TypeErrors are not IOErrors, so this will *not* be executed</span> </code></pre> <button class="clipboard-button" data-clipboard-text="Rails.error.handle(IOError) do 1 + "1" # raises TypeError end 1 + 1 # TypeErrors are not IOErrors, so this will *not* be executed ">Copy</button> </div> <p>Here, the <code>TypeError</code> will not be captured by the Rails error reporter. Only instances of <code>IOError</code> and its descendants will be reported. Any other errors will be raised as normal.</p><h3 id="disabling-notifications"><a class="anchorlink" href="#disabling-notifications" data-turbo="false"><span>1.6</span> Disabling Notifications</a></h3><p>You can prevent a subscriber from being notified of errors for the duration of a block by calling <a href="https://api.rubyonrails.org/v8.0.0/classes/ActiveSupport/ErrorReporter.html#method-i-disable"><code>Rails.error.disable</code></a>. Similarly to <code>subscribe</code> and <code>unsubscribe</code>, you can pass in either the subscriber itself, or its class.</p><div class="interstitial code"> <pre><code class="highlight ruby"><span class="no">Rails</span><span class="p">.</span><span class="nf">error</span><span class="p">.</span><span class="nf">disable</span><span class="p">(</span><span class="no">ErrorSubscriber</span><span class="p">)</span> <span class="k">do</span> <span class="mi">1</span> <span class="o">+</span> <span class="s2">"1"</span> <span class="c1"># TypeError will not be reported via the ErrorSubscriber</span> <span class="k">end</span> </code></pre> <button class="clipboard-button" data-clipboard-text="Rails.error.disable(ErrorSubscriber) do 1 + "1" # TypeError will not be reported via the ErrorSubscriber end ">Copy</button> </div> <div class="interstitial note"><p>This can also be helpful for third-party error reporting services who may want to manage error handling a different way, or higher in the stack.</p></div><h2 id="error-reporting-libraries"><a class="anchorlink" href="#error-reporting-libraries" data-turbo="false"><span>2</span> Error-reporting Libraries</a></h2><p>Error-reporting libraries can register their subscribers in a <a href="https://api.rubyonrails.org/v8.0.0/classes/Rails/Railtie.html">Railtie</a>:</p><div class="interstitial code"> <pre><code class="highlight ruby"><span class="k">module</span> <span class="nn">MySdk</span> <span class="k">class</span> <span class="nc">Railtie</span> <span class="o"><</span> <span class="o">::</span><span class="no">Rails</span><span class="o">::</span><span class="no">Railtie</span> <span class="n">initializer</span> <span class="s2">"my_sdk.error_subscribe"</span> <span class="k">do</span> <span class="no">Rails</span><span class="p">.</span><span class="nf">error</span><span class="p">.</span><span class="nf">subscribe</span><span class="p">(</span><span class="no">MyErrorSubscriber</span><span class="p">.</span><span class="nf">new</span><span class="p">)</span> <span class="k">end</span> <span class="k">end</span> <span class="k">end</span> </code></pre> <button class="clipboard-button" data-clipboard-text="module MySdk class Railtie < ::Rails::Railtie initializer "my_sdk.error_subscribe" do Rails.error.subscribe(MyErrorSubscriber.new) end end end ">Copy</button> </div> <div class="interstitial note"><p>If you register an error subscriber, but still have other error mechanisms like a Rack middleware, you may end up with errors reported multiple times. You should either remove your other mechanisms or adjust your report functionality so it skips reporting an error it has seen before.</p></div> </section> <hr> <footer aria-labelledby="heading-feedback" role="region"> <h2 id="heading-feedback">Feedback</h2> <p> You're encouraged to help improve the quality of this guide. </p> <p> Please contribute if you see any typos or factual errors. To get started, you can read our <a href="https://edgeguides.rubyonrails.org/contributing_to_ruby_on_rails.html#contributing-to-the-rails-documentation">documentation contributions</a> section. </p> <p> You may also find incomplete content or stuff that is not up to date. Please do add any missing documentation for main. Make sure to check <a href="https://edgeguides.rubyonrails.org">Edge Guides</a> first to verify if the issues are already fixed or not on the main branch. Check the <a href="ruby_on_rails_guides_guidelines.html">Ruby on Rails Guides Guidelines</a> for style and conventions. </p> <p> If for whatever reason you spot something to fix but cannot patch it yourself, please <a href="https://github.com/rails/rails/issues">open an issue</a>. </p> <p>And last but not least, any kind of discussion regarding Ruby on Rails documentation is very welcome on the <a href="https://discuss.rubyonrails.org/c/rubyonrails-docs">official Ruby on Rails Forum</a>. </p> </footer> </div> </article> </main> <hr class="hide" /> <footer id="complementary"> <div class="wrapper"> <p>This work is licensed under a <a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative Commons Attribution-ShareAlike 4.0 International</a> License</p> <p>"Rails", "Ruby on Rails", and the Rails logo are trademarks of David Heinemeier Hansson. All rights reserved.</p> </div> </footer> <a href="#main-skip-link" class="back-to-top" data-turbo="false"><span class="visibly-hidden">Back to top</span></a> </body> </html>

CINXE.COM

Error Reporting in Rails Applications — Ruby on Rails Guides