jQuery Error Event

What You’ll Learn

The error event fires when the browser fails to load a resource such as an image. This tutorial covers .on("error"), attaching handlers before src, fallback swapping, .one("error"), .trigger("error"), the official jQuery API demos, and how this differs from load, window.onerror, and the removed .error() method.

Introduction

Broken avatars, missing product photos, and dead CDN links all show the same ugly browser placeholder unless your code catches the failure first. The error event is jQuery’s hook for that moment — when an element such as <img> cannot load its resource.

The official jQuery API distinguishes the error event (bound with .on("error") since 1.7) from the removed .error() method (Ajax shorthand, gone in jQuery 3.0). To programmatically run error handlers, use .trigger("error") since jQuery 1.0.

Understanding the error Event

The error event is sent to elements, such as images, that are referenced by a document and loaded by the browser. It is called if the element was not loaded correctly — for example, when the URL returns a 404 or the file is unreachable.

It applies to resource elements the browser loads directly — most commonly <img>, and also <script> and <link> in supporting browsers. It is not the same as catching JavaScript exceptions on window; for script errors, use window.onerror instead.

📝 Syntax

The modern jQuery API for the error event has two main forms — binding a handler and triggering the event:

1. Bind a handler — .on("error" [, eventData ], handler) (since 1.7)

.on( "error" [, eventData ], handler )

• eventData — optional object passed to the handler as event.data.
• handler — function called when the resource fails: function( event ) { ... }.

2. Event delegation — .on("error", selector, handler)

$( "#gallery" ).on( "error", "img", function( event ) {
  // runs when any img inside #gallery fails to load — including future ones
} );

Attach delegation on a container, then set src on child images — one handler covers dynamic galleries.

3. Trigger the event — .trigger("error") (since 1.0)

.trigger( "error" )

• Runs bound error handlers on the matched element(s).
• Does not simulate a real network failure — it fires jQuery-bound handlers only.

4. Unbind — .off("error" [, selector] [, handler])

$( "#book" ).off( "error" );                 // remove all error handlers
$( "#gallery" ).off( "error", "img", fn );   // remove delegated handler

Official jQuery API examples

$( "#book" )
  .on( "error", function() {
    alert( "Handler for `error` called." );
  } )
  .attr( "src", "missing.png" );

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

Return value

• .on() and .trigger() 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 images.

Examples Gallery

Examples 1–3 follow the official jQuery API documentation. Examples 4–5 extend the pattern with multi-image logging and a one-time SVG fallback. Use the Try-it links to run each snippet in the browser.

$( "#book" )
  .on( "error", function() {
    alert( "Handler for `error` called." );
  } )
  .attr( "src", "missing.png" );

Page loads → browser requests missing.png → 404

error event fires → alert: Handler for error called.

Handler must be bound before .attr("src") runs

// If missing.png is missing, it is replaced by replacement.png
$( "img" )
  .on( "error", function() {
    $( this ).attr( "src", "replacement.png" );
  } )
  .attr( "src", "missing.png" );

Both thumbnails request broken URLs → error fires on each

Handler sets src to valid fallback → placeholder images appear

Log shows "Replaced: Photo A" and "Replaced: Photo B"

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

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

Image loads normally with valid src

Click Trigger the handler → trigger("error") → handler runs

Useful for testing fallback UI without a real network failure

$( ".gallery img" ).each( function() {
  var $img = $( this );
  $img.on( "error", function() {
    $( "#log" ).append(
      "<div>error on id=" + $img.data( "id" ) +
      " (" + $img.attr( "alt" ) + ")</div>"
    );
  } ).attr( "src", "missing-" + $img.data( "id" ) + ".png" );
} );

Three gallery images request broken URLs

Log fills with:
  error on id=1 (Item 1)
  error on id=2 (Item 2)
  error on id=3 (Item 3)

var fallbackSvg = "data:image/svg+xml," + encodeURIComponent(
  '<svg xmlns="http://www.w3.org/2000/svg" width="96" height="96">' +
  '<rect fill="#e2e8f0" width="96" height="96"/>' +
  '<text x="48" y="54" text-anchor="middle" fill="#64748b" font-size="12">User</text>' +
  '</svg>'
);

$( "#avatar" )
  .one( "error", function() {
    $( this ).attr( "src", fallbackSvg );
  } )
  .attr( "src", "missing-avatar.png" );

Broken avatar URL → error fires once

Handler swaps to inline SVG data URI → gray "User" placeholder

.one() removes handler → no loop even if something else fails later

🚀 Common Use Cases

• Broken image placeholders — swap to a default avatar or “image unavailable” graphic when CDN links die.
• User-uploaded content — catch failed profile photos and show a generic silhouette.
• Product galleries — log which SKUs have missing images for admin dashboards.
• Lazy-loaded thumbnails — attach error handlers before setting deferred src values.
• Graceful degradation — hide broken <script> or stylesheet failures with paired error handlers where supported.
• Testing fallback UI — use .trigger("error") to verify handler logic without breaking real URLs.

📝 Notes

• Bind with .on("error", handler) since jQuery 1.7 — not the removed .error() Ajax method.
• Trigger with .trigger("error") since jQuery 1.0.
• Attach the handler before setting src — the official API requirement.
• The file: protocol often does not fire error reliably — test over HTTP/HTTPS.
• Do not bind jQuery error on window for script errors — use window.onerror.
• Ensure fallback images exist — otherwise error loops indefinitely.
• Use .one("error") or inline data: URIs for safe one-shot fallbacks.
• Use .off("error") to remove handlers — avoid deprecated .unbind("error").

💡 Best Practices