The Astro Image Gotcha That Broke Our Production Build and How We Fixed It

Rachid — Thu, 30 Jul 2026 23:07:05 +0000

We ship a bilingual (French/Arabic) marketplace site built on Astro — static output, hundreds of location plus service pages, and a few thousand professional profile pages, each with a photo pulled from Firebase Storage. Nothing exotic. Then one day the production build just... died. No warning during local dev, no failing test, no lint error. npm run build exited non-zero, and the stack trace pointed at astro:assets.

The cause, once I dug in: one profile's photo URL had gone stale. A Firebase Storage download token had rotated, so a request that used to return a JPEG now returned a 403. That's it. One dead URL, out of a few thousand, took the entire build down with it.

That surprised me, because I assumed Astro's image pipeline would fail soft on a bad remote image — log a warning, skip it, move on. It doesn't. Here's why, and what we did about it.

Why can't catch this

Astro's component and the underlying getImage() function both hand off to an Image Service, whose job is to transform() the image — resize it, convert format, whatever your config says. That's the part you can hook into and customize.

The problem is that transform() only ever receives an image that's already been fetched, as a raw buffer. The actual network request for a remote src happens earlier inside Astro's own internal loadRemoteImage step — whixh isn't part of the public, pluggable Image Service API. There's no supported hook that sits between "here's a remote URL" and "here's the fetched buffer" where you can intercept a failed request and decide what to do about it.

So from the framework's point of view, a 403 or a timeout on a remote image isn't a "handle this gracefully" situation — it's a fatal error during static generation. If even one image URL in your dataset is dead, the whole build stops.

The two-minute fix (and why it's not enough)

The fastest way out is obvious: swap for a plain tag. That sidesteps Astro's build-time fetch-and-transform step entirely, because a plain just emits the URL as-is and lets the browser deal with it at runtime.

That got our deploys unblocked immediately, but it's a real trade-off, not a fix — you lose automatic resizing, format conversion (WebP/AVIF), and the responsive srcset handling that's the entire reason to use in the first place. Fine as a stopgap. Not something to leave in place.

The actual fix: check before you build, not during

The real problem wasn't that Astro handles failures badly — it's that we were handing Astro URLs we hadn't verified. So we moved the verification earlier, into a prebuild step that runs before Astro ever touches an image.

The script is small: collect every unique remote image URL your pages will reference, HEAD-check each one with a timeout, and write the ones that fail to a JSON manifest.

js
// scripts/validate-image-urls.mjs
import fs from "node:fs";

const TIMEOUT_MS = 8000;
const CONCURRENCY = 10;

async function checkUrl(url) {
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
try {
const res = await fetch(url, { method: "HEAD", signal: controller.signal });
return res.ok;
} catch {
return false; // timeout, DNS failure, connection reset — all treated as "bad"
} finally {
clearTimeout(timer);
}
}

Two design decisions mattered more than the code itself:

Fail closed per URL, fail open in aggregate. If a single URL times out or errors, treat it as bad — that's the safe default for one image. But if, say, 70% of all URLs fail in the same run, that's not "most of our images died overnight," that's almost certainly the checker itself being broken — offline CI runner, DNS hiccup, rate limiting. In that case the script leaves the existing manifest untouched rather than blanking every photo on the site. A partial network failure in your validation step shouldn't be able to nuke your production content.

Hook it in with prebuild, not an Astro integration. We wired this through npm's own lifecycle ("prebuild": "node scripts/validate-image-urls.mjs" in package.json), which runs automatically before build. We deliberately skipped writing it as an Astro integration hook — it's simpler, it's fully decoupled from Astro's internal build order, and it'd survive a framework migration untouched.

On the component side, it's a one-line check:

astro

import { isBadImageUrl } from "../utils/badImageUrls";

const showFallback = isBadImageUrl(profile.thumbnail);

{showFallback
? /* render an initials avatar instead / null
: / render the optimized Image component with profile.thumbnail as the source */ null}

Known-bad URLs get a graceful fallback (initials avatar) instead of ever reaching . Everything else gets the full optimization pipeline as normal.

Does it actually work at scale?

The first real production run checked several thousand unique image URLs against the live network in a few seconds thanks to the concurrency limit, and it did exactly what it was supposed to: flagged a handful of genuinely dead URLs, left everything else alone, and the build stopped depending on the uptime of every single image host on the internet.

One small habit that paid off while shipping this: when I reverted the emergency fallback back to once the validator was in place, I diffed against git history (git show HEAD:path/to/file) instead of trusting my memory of what the original props looked like. Cheap insurance — worth doing any time you're undoing an emergency fix under time pressure.

The takeaway

If you're using Astro's or getImage() with remote sources you don't fully control — user uploads, a CMS, cloud storage — don't assume a bad URL fails gracefully. It doesn't, by design, because the fetch happens in a part of the pipeline you can't hook into. Validate before the build starts, not during it.

We run this on bricoleapp.com, a bilingual home-services marketplace for Morocco and Egypt — happy to go deeper on any part of this if it's useful.

DEV Community: Rachid

The Astro Image Gotcha That Broke Our Production Build and How We Fixed It

astro

const showFallback = isBadImageUrl(profile.thumbnail);