jQuery .error() Method

What You’ll Learn

The .error() method is jQuery’s legacy shorthand for binding and triggering the error event on elements such as images. This tutorial covers .error(handler) since 1.0, .error(eventData, handler) since 1.4.3, no-argument .error() as a trigger, migration to .on("error") and .trigger("error"), and why the entire method was removed in jQuery 3.0 after being deprecated since 1.8. See the jQuery error event tutorial for the modern API.

Introduction

Before jQuery 1.7 unified events with .on() and .off(), every common event had a matching shorthand — .error(), .load(), .click(), and more. The .error() method let you catch broken images in one short call: $("#book").error(function(){ alert("Handler for error called."); }).attr("src", "missing.png");. It was deprecated since jQuery 1.8 and removed entirely in jQuery 3.0.

Understanding .error() matters when reading older image-fallback and gallery tutorials in legacy codebases. The method did two distinct jobs: with a function argument it binds; with no arguments it triggers. Modern jQuery splits those roles explicitly — .on("error", handler) for binding and .trigger("error") for firing.

Understanding the .error() Method

The official jQuery API describes .error() as a way to bind an event handler to the error event, or trigger that event on an element. When you pass a handler, jQuery registers it on each matched element and calls it when the browser fails to load a resource — the same error event that .on("error") handles today on images, scripts, and other loadable elements.

When you call .error() with no arguments, jQuery synthetically fires the error event on each matched element. Bound handlers run once per call. This trigger behavior is equivalent to .trigger("error").

📝 Syntax

The .error() method has three signatures from the official jQuery API. All three were removed in jQuery 3.0 — use the modern replacements below:

1. Bind a handler — .error( handler ) (since 1.0, deprecated 1.8, removed 3.0)

.error( handler )

• handler — function executed each time the error event fires: function( event ) { ... }.
• Returns the jQuery object for chaining.
• Modern replacement: .on( "error", handler ).

2. Bind with eventData — .error( [eventData], handler ) (since 1.4.3, deprecated 1.8, removed 3.0)

.error( [eventData], handler )

• eventData — optional object available in the handler as event.data.
• Modern replacement: .on( "error", eventData, handler ).

3. Trigger the event — .error() (since 1.0, removed 3.0)

.error()

• No arguments — triggers error on every matched element.
• Runs bound error handlers.
• Modern replacement: .trigger( "error" ).

Official jQuery API migration note

// Removed binding
$( "#book" ).error( function() {
  alert( "Handler for `error` called." );
} );

// Modern binding
$( "#book" ).on( "error", function() {
  alert( "Handler for `error` called." );
} );

// Removed trigger
$( "#book" ).error();

// Modern trigger
$( "#book" ).trigger( "error" );

Return value

• All .error() signatures return the original jQuery object for chaining.
• Inside the handler, this refers to the DOM element that failed to load — use $(this).attr("src", fallback) to swap broken images.

Examples Gallery

Five examples cover binding on #book, eventData fallbacks, triggering, migration from .error() to .on("error"), and chaining on multiple images. Use the Try-it links to run each snippet in the browser. Examples 1–3 and 5 use jQuery 1.12.4 because .error() was removed in jQuery 3.0.

$( "#book" )
  .error( function() {
    alert( "Handler for \`error\` called." );
  } )
  .attr( "src", "https://httpstat.us/404" );

Page loads → browser requests 404 URL → error fires

Alert: Handler for error called.

Uses jQuery 1.12.4 — .error() removed in jQuery 3.0

Modern: .on("error", fn).attr("src", url)

var fallback = "https://via.placeholder.com/96/cccccc/666666?text=User";

$( "#avatar" ).error( { label: "avatar" }, function( event ) {
  $( "#out" ).text( "Failed: " + event.data.label + " → swapping fallback" );
  $( this ).attr( "src", fallback );
} );

$( "#load" ).on( "click", function() {
  $( "#avatar" ).attr( "src", "https://httpstat.us/404" );
} );

Click Load broken URL → avatar requests 404

"Failed: avatar → swapping fallback" → placeholder image appears

eventData.label passed without a closure

Modern: .on("error", { label: "avatar" }, fn)

$( "#book" ).error( function() {
  $( "#out" ).text( "Handler for error called (via .error() trigger)." );
} );

$( "#other" ).on( "click", function() {
  $( "#book" ).error();
} );

Image loads normally with valid src

Click Trigger with .error() → $("#book").error() → handler runs

No-arg .error() is trigger shorthand — prefer .trigger("error")

Removed in jQuery 3.0 along with binding form

// jQuery 3.7.1 — .error() is removed
if ( typeof $.fn.error === "undefined" ) {
  console.log( "$.fn.error is undefined in jQuery 3.x" );
}

$( "#legacy" )
  .on( "error", function() {
    $( "#log" ).append( "<div>Modern .on('error') handler ran</div>" );
    $( this ).attr( "src", "https://via.placeholder.com/100/cccccc/666666?text=OK" );
  } )
  .attr( "src", "https://httpstat.us/404" );

Log: $.fn.error is undefined in jQuery 3.x ✓

Broken src → .on("error") handler runs → fallback image appears

Legacy .error(fn) would throw TypeError in jQuery 3.x

var fallback = "https://via.placeholder.com/90/cccccc/666666?text=—";
var count = 0;

$( "img.thumb" )
  .error( function() {
    count++;
    $( this ).attr( "src", fallback );
    $( "#log" ).text( "Legacy .error() swapped " + count + " broken image(s)." );
  } )
  .attr( "src", "https://httpstat.us/404" );

Three thumbnails request broken URLs → error fires on each

Each handler swaps src to gray placeholder

Log: "Legacy .error() swapped 3 broken image(s)."

Same attach-before-src rule applies to .on("error")

🚀 Common Use Cases

• Reading legacy code — recognize $("#book").error(fn) as equivalent to .on("error", fn) in older image-fallback scripts.
• Broken image placeholders — legacy tutorials bind .error() to swap dead CDN links with default avatars.
• Programmatic trigger — $("#book").error() from a test button — replace with .trigger("error").
• Shared eventData — $("#avatar").error({ label: "avatar" }, fn) passes metadata without closures.
• Gallery thumbnails — chained .error(fn).attr("src", url) on multiple images in one call.
• Maintaining legacy jQuery 1.x sites — many older panels still use .error() — know how to migrate before upgrading to jQuery 3.x.

📝 Notes

• Removed in jQuery 3.0 — do not use .error(handler), .error(eventData, handler), or no-arg .error() in jQuery 3.x. Use .on("error") and .trigger("error") instead.
• Deprecated since jQuery 1.8; binding form available since 1.0; eventData form since 1.4.3.
• Attach the handler before setting src — the official jQuery API requirement for both legacy and modern APIs.
• .error() does not support event delegation — use .on("error", "img", fn) for dynamic galleries.
• The file: protocol often does not fire error reliably — test over HTTP/HTTPS.
• Do not confuse element error with window.onerror for JavaScript exceptions.
• Ensure fallback images exist — otherwise error loops indefinitely after swapping src.
• Remove handlers with .off("error") — not by calling .error(undefined).
• For the full modern error guide — fallbacks, delegation, and .one("error") — see the jQuery error event tutorial.

💡 Best Practices