jQuery .error() Method

What You’ll Learn

jQuery.error(message) throws an exception from a string. This tutorial covers the default throw behavior, the official override pattern (log then throw), try/catch, plugin validation, comparison with throw new Error(), five examples, and try-it labs.

Introduction

Plugin authors often need a single place to report “this option is invalid” or “this method was called wrong.” Since jQuery 1.4.1, jQuery.error(message) is that hook: it takes a string and throws.

The real power is overrideability. Apps can replace jQuery.error to send messages to a logging service, then still throw so callers and the debugger behave the same.

For everyday app code, throw new Error(message) is clearer. Learn jQuery.error so you can read plugins, wire reporting, and avoid silent overrides. See the Utilities hub for related helpers, and jQuery.readyException for ready-callback errors (a different API).

Understanding the jQuery.error() Method

By default, jQuery.error(message) throws an exception whose content comes from message. Execution stops at that line unless a try/catch handles it.

Overriding is intentional: assign jQuery.error = function(message) { … }. The official docs show logging first, then throw new Error(message). Skipping the throw changes semantics and can hide bugs.

📝 Syntax

Signature (jQuery 1.4.1+):

jQuery.error( message )

Parameters

• message (String) — the text included in the thrown exception.

Return value

• Does not return — it throws. There is no normal completion path.

Official override pattern

jQuery.error = function( message ) {
  sendErrorLog( "jQuery error: " + message );
  throw new Error( message );
};

Examples Gallery

Examples follow the official jQuery API and common plugin patterns. Use View Output or Try It Yourself to explore each case.

jQuery.error( "Something went wrong in the plugin" );

Uncaught Error: Something went wrong in the plugin

(or equivalent exception containing the message)

jQuery.error = function( message ) {
  // sendErrorLog( "jQuery error: " + message );
  console.error( "jQuery error:", message );
  throw new Error( message );
};

jQuery.error( "Logged and rethrown" );

console.error: jQuery error: Logged and rethrown
Then: Uncaught Error: Logged and rethrown

Logging without throw would hide the failure

try {
  jQuery.error( "Recoverable plugin issue" );
} catch ( err ) {
  $( "#out" ).text( "Caught: " + err.message );
}

Caught: Recoverable plugin issue

Page continues after the catch block

$.fn.spotlight = function( options ) {
  if ( !options || !options.color ) {
    jQuery.error( "spotlight: options.color is required" );
  }
  return this.css( "background-color", options.color );
};

// Throws — missing color
// $( "p" ).spotlight( {} );

// OK
$( "p" ).spotlight( { color: "#fde68a" } );

Valid call: paragraph background set
Invalid call: jQuery.error("spotlight: options.color is required")

Prefix messages with the plugin name for easier debugging

// Native — not routed through jQuery.error
// throw new Error( "native" );

// Hookable — plugins/apps can override jQuery.error
jQuery.error( "via jQuery.error" );

Both throw Error-like exceptions by default
Only jQuery.error can be globally overridden as one function

Use native throw in app code; use jQuery.error in plugin APIs

🚀 Common Use Cases

• Plugin argument checks — reject missing selectors, options, or types with a clear message.
• Central logging — override once to ship every jQuery.error call to your monitor.
• Internal assertions — jQuery and plugins can share one throw helper.
• Dev-only guards — fail loudly when APIs are misused during development.
• Reading legacy plugins — recognize $.error("…") as a deliberate throw.
• Not for network errors — use Ajax callbacks / deferreds for HTTP failures.

📝 Notes

• Added in jQuery 1.4.1; still present in modern jQuery 3.x.
• Primary audience: plugin developers, not everyday app scripts.
• If you override, still throw at the end (official requirement).
• Not related to Ajax error options or the old .error() event shorthand.
• Different from jQuery.readyException (ready-callback sync errors).
• Prefer throw new Error() in application modules unless you need the hook.
• Prefix plugin messages with the plugin name for searchable logs.

💡 Best Practices