Fix: Unsupported Image Format in Astro

What Causes This Error?

This error occurs when you try to use an image format that isn’t supported by Astro’s image optimization service. The default Sharp service supports common formats but has limitations.

The Problem

---
import { Image } from 'astro:assets';
// ❌ Format not supported for optimization
import animation from '../assets/animation.gif';
---

<Image src={animation} alt="Animation" />

The Fix

Use Supported Formats

---
import { Image } from 'astro:assets';
// ✅ Supported formats: jpg, jpeg, png, webp, avif, tiff
import photo from '../assets/photo.jpg';
---

<Image src={photo} alt="Photo" />

Skip Optimization for Unsupported Formats

---
// Import as URL to skip processing
import gifUrl from '../assets/animation.gif?url';
---

<!-- ✅ Use native img tag -->
<img src={gifUrl} alt="Animation" />

Common Scenarios

Animated GIFs

---
// GIFs lose animation when optimized
// Import as URL instead
import animatedGif from '../assets/loading.gif?url';
---

<!-- ✅ Preserves animation -->
<img src={animatedGif} alt="Loading animation" />

SVG Files

---
// SVGs should be used directly, not optimized
import logoUrl from '../assets/logo.svg?url';

// Or import as component for inline SVG
import Logo from '../assets/logo.svg?component';
---

<!-- Option 1: As image src -->
<img src={logoUrl} alt="Logo" />

<!-- Option 2: Inline SVG (with astro-svg integration) -->
<Logo />

ICO Files

---
// ICO files aren't supported
// Place in public folder instead
---

<!-- ✅ Reference from public directory -->
<link rel="icon" href="/favicon.ico" />

HEIC/HEIF Images

---
// HEIC from iPhones not supported
// Convert to JPEG first
import photo from '../assets/photo.jpg'; // Converted version
---

<Image src={photo} alt="Photo" />

BMP Files

---
// BMP not supported, convert to PNG or JPEG
import image from '../assets/image.png'; // Converted
---

<Image src={image} alt="Image" />

WebP and AVIF Output

---
import { Image } from 'astro:assets';
import photo from '../assets/photo.jpg';
---

<!-- ✅ Convert TO these formats -->
<Image src={photo} alt="Photo" format="webp" />
<Image src={photo} alt="Photo" format="avif" />

Picture Component for Format Fallbacks

---
import { Picture } from 'astro:assets';
import photo from '../assets/photo.jpg';
---

<!-- ✅ Multiple format outputs -->
<Picture
  src={photo}
  alt="Photo"
  formats={['avif', 'webp', 'jpg']}
/>

Supported Input Formats

Format	Supported	Notes
JPEG/JPG	✅	Fully supported
PNG	✅	Fully supported
WebP	✅	Fully supported
AVIF	✅	Fully supported
TIFF	✅	Supported
GIF	⚠️	Static only, use ?url for animated
SVG	❌	Use ?url or ?component
ICO	❌	Use public folder
BMP	❌	Convert first
HEIC	❌	Convert first

Converting Images

# Using ImageMagick
convert input.bmp output.png
convert input.heic output.jpg

# Using Sharp CLI
npx sharp -i input.heic -o output.jpg

Quick Checklist

• Use JPEG, PNG, WebP, AVIF, or TIFF for Image component
• Use ?url suffix for unsupported formats
• Put SVGs in public or use as components
• Convert HEIC, BMP, ICO before using
• Animated GIFs need ?url to preserve animation