HTML onerror Attribute

Introduction

The onerror attribute is an inline event handler that runs JavaScript when the error event fires. That happens when an external resource fails to load — a broken image URL, a missing script file, or a media file the browser cannot decode. The most common beginner pattern is an <img> that swaps to a fallback image. Use onerror to keep pages usable when assets fail, log failures, or show placeholder content. It is not the same as onabort (load canceled) or window.onerror (uncaught JavaScript exceptions).

What You’ll Learn

Purpose of onerror Attribute

The primary purpose of onerror is to recover gracefully when resources fail. A product photo might 404 — show a placeholder instead of a broken icon. A CDN script might be blocked — load a local backup or disable a feature safely. Media that cannot decode fires error on audio or video.

Always guard against infinite loops: if the fallback image also fails, clear onerror or check that you have not already swapped the source before assigning a new src.

📝 Syntax

Set onerror on an element that loads external content:

<img src="photo.jpg" alt="Product" onerror="handleImageError(this)">

<script>
  function handleImageError(img) {
    img.onerror = null;
    img.src = "/images/placeholder.png";
  }
</script>

Syntax Rules

• Value is JavaScript executed when the error event fires.
• Common on <img>, <script src>, <audio>, <video>, <link>, <track>.
• Fires on load failure — not when loading is intentionally aborted (onabort).
• JavaScript: element.onerror = function() { … }.
• Modern alternative: element.addEventListener("error", handler).
• Clear onerror after swapping src to avoid infinite error loops.

💎 Values

The onerror attribute accepts a string of JavaScript code:

• onerror="handleError()" — Call a named function.
• onerror="this.onerror=null;this.src='fallback.png'" — Inline one-liner fallback.
• JavaScript: img.onerror = () => { … } assigns the handler.

const img = document.getElementById("avatar");

img.addEventListener("error", () => {
  img.onerror = null;
  img.src = "/images/default-avatar.png";
  img.alt = "Default avatar";
});

Applicable Elements

onerror vs onabort vs onload

Examples Gallery

Image fallback with inline onerror, addEventListener, and a compact one-liner pattern.

👀 Live Preview

The image below uses a broken URL — error swaps in a fallback:

Waiting for error handler…

Example — Image fallback with handleImageError

Log the failure and swap to a placeholder:

inline-onerror.html

Copy

<script>
  function handleImageError(img) {
    console.log("Error loading image!");
    img.onerror = null;
    img.src = "fallback.jpg";
  }
</script>

<img src="example.jpg" alt="Product photo" onerror="handleImageError(this)">

View Output Try It Yourself

📤 Output:

When example.jpg fails, handleImageError(this) runs and sets a fallback src. Always keep meaningful alt text.

How It Works

Pass this from the inline handler so the function can update the same img element. Clearing onerror prevents a loop if the fallback also fails.

Dynamic Values with JavaScript

Attach the handler with addEventListener:

dynamic-onerror.html

Copy

<script>
  var img = document.getElementById("dynamicImage");

  img.addEventListener("error", function () {
    console.log("Dynamic image loading error!");
    this.onerror = null;
    this.src = "dynamic-fallback.jpg";
  });

  // Or property form:
  img.onerror = function () { /* … */ };
</script>

View Output Try It Yourself

📤 Output:

addEventListener("error", …) keeps markup clean and supports multiple handlers on one element.

How It Works

Register the listener once at page load. When the image request fails, your recovery logic runs before the user sees a broken icon.

Example — Compact inline fallback

A common one-liner for simple placeholder swaps:

onerror-oneliner.html

Copy

<img
  src="avatar.jpg"
  alt="User avatar"
  onerror="this.onerror=null;this.src='default-avatar.png';">

View Output Try It Yourself

📤 Output:

this.onerror=null is essential — without it, a failing fallback retriggers error forever.

How It Works

Setting this.onerror = null inside the handler prevents infinite loops if the fallback URL also fails.

♿ Accessibility

• Update alt on fallback — If the placeholder conveys different meaning, change alt text in the error handler.
• Do not rely on broken icons — Users with slow networks deserve a visible fallback, not an empty box.
• Avoid alert() on error — Log silently or show non-blocking UI instead.
• Decorative images — Use alt="" when appropriate; still provide fallbacks for layout stability if needed.
• Announce critical failures — For essential content, use a live region if the fallback is text-only.

💡 Best Practices