How to Fix Broken Images in HTML with onerror
Use the HTML img onerror fallback pattern to replace broken images with stable fallback.pics URLs while preserving layout, alt text, and production safety.
The HTML img onerror fallback pattern is the fastest way to replace a failed image request with a controlled visual state.
A production-ready fallback needs more than a replacement URL: clear the error handler, keep dimensions stable, preserve useful alt text, and avoid putting private values in URL text.
Search intent
What the img onerror fallback actually fixes
Developers search for img onerror fallback when an image URL can be empty, deleted, blocked, corrupted, or unavailable at render time. The browser fires the image error handler after the resource fails, giving your markup one chance to swap in a safer source.
The goal is not to hide every media problem. The goal is to keep the interface readable while logs, monitoring, or CMS workflows handle the upstream issue.
Product grids
Replace missing catalog photos without collapsing card height or pushing prices out of alignment.
CMS previews
Keep editorial previews usable when a media field is empty or a remote asset has been removed.
Dashboards
Use consistent report, user, and workspace preview states instead of browser broken-image icons.
One-line fix
Basic img onerror fallback pattern
Start with the real image URL in src. If that request fails, clear the handler and set src to a fallback.pics URL that matches the expected image slot.
Clearing this.onerror matters. If the fallback URL ever fails, the image will not keep retrying the same error handler in a loop.
<img
src="/images/product-photo.jpg"
width="600"
height="400"
alt="Product photo"
onerror="this.onerror=null;this.src='https://fallback.pics/api/v1/600x400?text=Image+Unavailable'"
/>Layout
Keep the fallback image the same size
Broken images often create a second UX problem: layout shift. If the original image was expected to be 600 by 400, the fallback URL should use 600x400 and the img element should keep width and height attributes.
For responsive cards, keep the same fallback aspect ratio as the final media and let CSS scale the rendered element.
<article class="product-card">
<img
class="product-card__image"
src="/products/jacket.jpg"
width="800"
height="800"
alt="Product photo"
loading="lazy"
decoding="async"
onerror="this.onerror=null;this.src='https://fallback.pics/api/v1/800x800/F4F4F5/18181B?text=Product+Image'"
/>
<h2>Everyday Jacket</h2>
</article>
<style>
.product-card__image {
width: 100%;
height: auto;
aspect-ratio: 1 / 1;
object-fit: cover;
}
</style>Accessibility
Do not let the fallback URL replace alt text
The fallback image is a visual state. The alt attribute should still describe the content or purpose of the image slot, not the implementation detail that a fallback service is being used.
For decorative images, an empty alt can still be correct. For product images, avatars, article thumbnails, and CMS media, keep the alt text meaningful to the surrounding content.
<!-- Better: describes the image slot -->
<img
src="/team/profile-photo.jpg"
width="96"
height="96"
alt="Team member profile photo"
onerror="this.onerror=null;this.src='https://fallback.pics/api/v1/avatar/96?text=User'"
/>
<!-- Avoid: exposes implementation instead of meaning -->
<img
src="/team/profile-photo.jpg"
width="96"
height="96"
alt="fallback.pics placeholder"
/>Data safety
Keep placeholder URL text public and generic
The text query parameter is useful for labels like Image Unavailable, Product Image, Avatar, or Preview. Do not put secrets, tokens, email addresses, order IDs, regulated data, or private customer details in the URL.
Image URLs can appear in browser history, CDN logs, analytics tools, screenshots, support tickets, and referrer data. Treat every placeholder label as public metadata.
<!-- Good: generic public label -->
https://fallback.pics/api/v1/600x400?text=Image+Unavailable
<!-- Good: useful UI context without private data -->
https://fallback.pics/api/v1/800x800?text=Product+Image
<!-- Avoid: private identifiers or customer-specific values in URL text -->Reusable pattern
Add the handler with JavaScript when markup is generated
Inline onerror is convenient for static HTML, CMS templates, Markdown renderers, and quick fixes. If your application generates image nodes from JavaScript, attach the same behavior as an event handler.
This keeps the fallback URL centralized and makes it easier to update colors, dimensions, or labels later.
<img
id="catalog-image"
src="/products/source-image.jpg"
width="600"
height="400"
alt="Catalog product image"
/>
<script>
const image = document.querySelector("#catalog-image");
const fallbackSrc =
"https://fallback.pics/api/v1/600x400/18181B/FFFFFF?text=Image+Unavailable";
image.addEventListener("error", () => {
image.src = fallbackSrc;
}, { once: true });
</script>Framework path
When to move beyond inline HTML
The HTML onerror pattern is a good baseline, but larger products should move fallback behavior into shared components. React, Next.js, CMS templates, and design systems all benefit from one place that handles missing src values and failed image loads.
Use the HTML guide for the immediate fix, then standardize the same fallback.pics URL rules in your framework layer.
HTML guide: https://fallback.pics/guides/img-onerror-fallback/
Broken image fallback page: https://fallback.pics/broken-image-fallback/
Placeholder image API: https://fallback.pics/placeholder-image-api/
React guide: https://fallback.pics/guides/react-image-fallback/
Next.js guide: https://fallback.pics/guides/nextjs-image-fallback/Checklist
Production checklist for broken image fallback
Before shipping, test the failure path directly by pointing src at a missing local file or a blocked test URL. Confirm the fallback appears, the layout does not jump, and the error handler does not loop.
Use the same fallback dimensions as the intended image, keep alt text tied to the content, lazy load non-critical images, and keep fallback labels generic enough for public logs.
Key takeaways
What to standardize before shipping
- Use img onerror fallback when a real image URL can fail after the page renders.
- Clear this.onerror before replacing src to prevent retry loops.
- Use fallback.pics URLs with the canonical /api/v1 route and matching dimensions.
- Keep alt text meaningful and independent from the fallback image implementation.
- Treat placeholder URL text as public metadata and avoid sensitive values.
Production fallback layer
Use fallback.pics anywhere an image URL is accepted.
Start with one deterministic URL and standardize fallback behavior across your design system.
Continue reading
Related articles
Placeholder Image API: Complete URL Syntax Guide for Developers
A practical URL syntax guide for using fallback.pics as a placeholder image API, with examples for dimensions, colors, text, avatars, and skeleton states.
Image Loading Best Practices for Better UX
Practical image loading patterns for faster perceived performance, lower layout shift, and cleaner fallback states in production interfaces.
Complete Guide to Image Placeholders in Web Development
Learn how image placeholders protect perceived performance, preserve layout, and keep product interfaces professional when media is missing or delayed.