jQuery readyException() Method

What Is jQuery.readyException()?

jQuery.readyException(error) (since 3.1) is the hook jQuery calls when a function wrapped in jQuery() / $(document).ready() throws synchronously. By default it re-throws inside setTimeout so the error reaches the console and window.onerror instead of being swallowed.

// Default behavior (conceptually):
jQuery.readyException = function (error) {
  window.setTimeout(function () {
    throw error;
  });
};

// Official override example:
jQuery.readyException = function (error) {
  console.error(error);
};

// Triggered by:
$(function () {
  throw new Error("Ready handler failed");
});

How to Use readyException

Overwrite the hook early, then let ready callbacks throw into it.

1. Load jQuery 3.1+ (the hook does not exist in older builds).
2. Assign jQuery.readyException = function (error) { … } before risky ready code.
3. Register ready callbacks with $(fn) or $(document).ready(fn).
4. On a sync throw, jQuery calls your hook with the Error.
5. Log, report, update UI — and optionally setTimeout(function () { throw error; }, 0) to keep default visibility.

Pseudocode

register ready callback fn via $(fn) or .ready(fn)

when DOM is ready:
    try:
        call fn()
    catch error:
        call jQuery.readyException(error)

default readyException(error):
    setTimeout → throw error   // console + window.onerror see it

custom readyException(error):
    log / report / update UI
    optionally rethrow in setTimeout

Cheat Sheet

Keep these facts handy when debugging ready-handler failures.

Live Preview

Override readyException, then run a ready callback that throws so you can see the hook fire on the page.

Ready — pick an action and click Run.

jQuery Examples

Short, copy-ready snippets. Open DevTools Console for console.error demos, or use Try It Yourself.

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

readyException receives Error: Ready handler failed
Default 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 → "Error: Missing config"
Handy for demos and internal tools
Production apps usually also report to a service

jQuery.readyException = function (error) {
  $("#log").text("Reported: " + error.message);
  window.setTimeout(function () {
    throw error;
  }, 0);
};

$(function () {
  throw new Error("Init crashed");
});

#log → "Reported: Init crashed"
Then an uncaught error appears in the console
window.onerror can still observe it

jQuery.readyException = function (error) {
  $("#log").text("readyException: " + error.message);
};

$(function () {
  $("#log").text("Ready ran. Scheduling async throw…");
  setTimeout(function () {
    throw new Error("Too late for readyException");
  }, 0);
});

#log stays on the "Ready ran…" message
readyException does NOT receive the async error
Use try/catch, promise .catch, or window.onerror instead

Performance Notes

The hook runs only when a ready callback fails. Keep it tiny: log, enqueue a report, optionally rethrow — do not rebuild the page there.

Key Takeaways