fix: report http status and content type when an image fails to load

[Nixxx19]

fixes #613
fixes #626
refs #575

when a remote image fails to load, satori reports Unsupported image type: unknown no matter what actually went wrong. the response status is never checked, so a 404 html page goes straight into the magic byte sniffer, comes back as null, and the user gets told their png is an unsupported format.

that is why those three issues have gone in circles for two years. people keep saying the same thing, the image opens fine in my browser, it works in dev and not in prod. of course it does, the url is 404ing in prod and nothing in the message says so.

on 0.33.4, an existing 404 and an html page produce the exact same output:

Can't load image https://raw.githubusercontent.com/vercel/satori/main/definitely-not-here.png: Unsupported image type: unknown
Can't load image https://example.com/: Unsupported image type: unknown

after this change:

Can't load image https://raw.githubusercontent.com/vercel/satori/main/definitely-not-here.png: the server responded with 404 Not Found (Content-Type: "text/plain; charset=utf-8")
Can't load image https://example.com/: Unsupported image type: unknown. The server sent Content-Type "text/html", which is not an image format Satori can decode.

two changes. the fetch path now fails when the response was not ok and says which status came back, and when the bytes really are unrecognised the error names the content type the server sent.

i used res.ok === false rather than !res.ok on purpose. satori lets you bring your own fetch, and the test polyfill in this repo returns a bare object with no ok on it, so a truthiness check would have thrown on every existing image test and on anyone with a similar polyfill. this way it only fires when a response positively reports failure.

#575 reports a cdn image rendering blank without quoting an error, so i have only linked it rather than closing it. if it is the same thing this change will finally say so in the log, and if it is cors or a redirect it will say that instead.

nothing about the fallback behaviour changes. a broken image is still swallowed and the rest of the render still succeeds, you just get told why.

added two tests, one per branch. both fail on main, i checked before adding them. suite is green locally, 514 tests.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
satori-playground	Ready	Preview, v0	Sep 1, 2026 6:57am UTC