image.transparent-declared
Image may be transparent. Level: Tip.
When it is raised
Raised when the image's header declares transparency but the API cannot measure how much of the image uses it. That is a WebP whose header sets the alpha flag, a GIF whose first Graphic Control Extension within the first 4,096 bytes of the file sets the transparency flag, or a PNG with an alpha channel or tRNS chunk that is over 25 million pixels or cannot be decoded from the bytes fetched (the API reads at most the first 2,500,000 bytes of the image). JPEG never raises it, and AVIF, SVG and other formats are not examined for transparency at all.
What it does to a shared link
If part of the image is see-through, those areas take whatever colour sits behind the image where it is displayed, and the page cannot choose that colour. og:image has no light or dark variant, so one file has to read against both a light and a dark background.
How to fix it
- Open the image and check whether any area is actually transparent, on both a white and a near-black background.
- If it is, flatten the image onto a solid background colour and re-export it; the command below takes a WebP, GIF or PNG as input.
- If the alpha channel is unused, re-export without it (for example as RGB PNG or JPEG) so the API can confirm the image is opaque.
- Give the new file a new URL so cached copies are not reused.
