jQuery .readyException() Method

What You’ll Learn

jQuery.readyException() is the hook jQuery calls when a ready callback throws. This tutorial explains the default setTimeout rethrow, how to override it for logging, what it does not catch, and five practical examples with try-it labs.

Introduction

Almost every jQuery page starts with $(function() { … }) or $(document).ready(…). If that function throws, you still want a clear error in the console — not a silent failure that leaves the UI half initialized.

Since jQuery 3.1, jQuery routes those synchronous exceptions through jQuery.readyException(error). The default implementation re-throws inside a timeout so DevTools and window.onerror still report the bug.

You can replace jQuery.readyException with your own function to log to a service, show a friendly message, or call console.error without rethrowing. Pair this topic with .ready() and jQuery.ready for the full ready lifecycle.

Understanding the jQuery.readyException() Method

When a callback registered via jQuery(fn) / jQuery(document).ready(fn) throws synchronously, jQuery catches the error and invokes jQuery.readyException(error) with that Error object.

The stock implementation schedules a rethrow so the exception is not eaten by jQuery’s internal try/catch. Overwrite the method if your app needs different handling — the official docs show piping to console.error.

📝 Syntax

Signature (jQuery 3.1+):

jQuery.readyException( error )

Parameters

• error — the Error (or throw value) from the ready callback.

Return value

• Not used by application code in practice — jQuery calls this hook for side effects (logging / rethrow).
• You overwrite the function; you rarely call it yourself.

Official override pattern

jQuery.readyException = function( error ) {
  console.error( error );
};

Examples Gallery

Examples follow the official jQuery API and common production overrides. Use Try It Yourself to see console and on-page logging.

$(function() {
  throw new Error( "Ready handler failed" );
});
// Default: error rethrown in setTimeout → appears in the console

readyException receives Error: Ready handler failed
Default implementation schedules a rethrow
DevTools shows an uncaught error shortly after

jQuery.readyException = function( error ) {
  console.error( error );
};

$(function() {
  throw new Error( "Logged via readyException" );
});

console.error shows the Error object
No automatic setTimeout rethrow (unless you add one)
Matches the official documentation sample

jQuery.readyException = function( error ) {
  $( "#error-box" ).text( String( error ) );
};

$(function() {
  throw new Error( "Missing config" );
});

#error-box text becomes "Error: Missing config"
Useful for demos and internal admin tools
Production apps usually log to a monitoring service

jQuery.readyException = function( error ) {
  // sendToMonitor( error ); // your APM / analytics
  console.warn( "readyException:", error );
  setTimeout( function() {
    throw error;
  }, 0 );
};

console.warn runs first
Then an uncaught error appears (setTimeout throw)
Mirrors the spirit of jQuery's default implementation

jQuery.readyException = function( error ) {
  console.error( "readyException:", error );
};

$(function() {
  setTimeout( function() {
    throw new Error( "Too late for readyException" );
  }, 0 );
});

readyException handler is NOT called
Timer throw becomes a normal uncaught error
Use try/catch, .catch on promises, or window.onerror for async work

🚀 Common Use Cases

• Central logging — send ready failures to Sentry, LogRocket, or your API.
• Friendlier demos — show on-page error text instead of only the console.
• Hardening apps — keep default rethrow so bugs stay visible in QA.
• Debugging init — distinguish ready-time throws from later click/Ajax errors.
• Teaching — explain why a broken $(function(){…}) still surfaces in DevTools.

📝 Notes

• Added in jQuery 3.1.
• Only synchronous throws in ready wrappers are handled.
• Default implementation rethrows via setTimeout so errors are not swallowed.
• Overwrite before registering risky ready handlers.
• Not a substitute for try/catch around async work or promise rejections.
• Related DOM APIs: .ready(), jQuery.ready, jQuery.holdReady().

💡 Best Practices