{"record":{"id":"c412ed775b708781","repo":"withastro/astro","slug":"unsupportedimageformat","errorCode":"UnsupportedImageFormat","errorMessage":"Received unsupported format `${format}` from `${imagePath}`. Currently only ${supportedFormats.join(', ')} are supported by our image services.","messagePattern":"Received unsupported format `(.+?)` from `(.+?)`\\. Currently only (.+?) are supported by our image services\\.","errorType":"exception","errorClass":"AstroError","httpStatus":null,"severity":"error","filePath":"packages/astro/src/assets/services/service.ts","lineNumber":199,"sourceCode":"\t\t// For remote images, width and height are explicitly required as we can't infer them from the file\n\t\tlet missingDimension: 'width' | 'height' | 'both' | undefined;\n\t\tif (!options.width && !options.height) {\n\t\t\tmissingDimension = 'both';\n\t\t} else if (!options.width && options.height) {\n\t\t\tmissingDimension = 'width';\n\t\t} else if (options.width && !options.height) {\n\t\t\tmissingDimension = 'height';\n\t\t}\n\n\t\tif (missingDimension) {\n\t\t\tthrow new AstroError({\n\t\t\t\t...AstroErrorData.MissingImageDimension,\n\t\t\t\tmessage: AstroErrorData.MissingImageDimension.message(missingDimension, options.src),\n\t\t\t});\n\t\t}\n\t} else {\n\t\tif (!VALID_SUPPORTED_FORMATS.includes(options.src.format as any)) {\n\t\t\tthrow new AstroError({\n\t\t\t\t...AstroErrorData.UnsupportedImageFormat,\n\t\t\t\tmessage: AstroErrorData.UnsupportedImageFormat.message(\n\t\t\t\t\toptions.src.format,\n\t\t\t\t\toptions.src.src,\n\t\t\t\t\tVALID_SUPPORTED_FORMATS,\n\t\t\t\t),\n\t\t\t});\n\t\t}\n\n\t\tif (options.widths && options.densities) {\n\t\t\tthrow new AstroError(AstroErrorData.IncompatibleDescriptorOptions);\n\t\t}\n\n\t\tif (options.src.format !== 'svg' && options.format === 'svg') {\n\t\t\tthrow new AstroError(AstroErrorData.UnsupportedImageConversion);\n\t\t}\n\t}\n}","sourceCodeStart":181,"sourceCodeEnd":217,"githubUrl":"https://github.com/withastro/astro/blob/e294953aa8aadd98d5be92e60a03037b05dbdfd4/packages/astro/src/assets/services/service.ts#L181-L217","documentation":"For ESM-imported images, `verifyOptions()` checks the import's declared `format` against the formats the image services can process — `jpeg, jpg, png, tiff, webp, gif, svg, avif` (packages/astro/src/assets/consts.ts:25) — and throws `UnsupportedImageFormat` listing the supported set (packages/astro/src/assets/services/service.ts:188).","triggerScenarios":"Importing an `.ico`, `.bmp`, `.heic`, or other exotic file through `import x from './icon.ico'` and passing it to `<Image>`/`getImage()`.","commonSituations":"Favicons and legacy assets in `.ico`/`.bmp`; designer handoffs with `.heic`/`.tiff` (tiff is supported, heic is not); assets shared with non-web projects.","solutions":["Convert the file to a supported format (png/webp for bitmaps, svg for vector) and re-import.","For `.ico` favicons referenced verbatim, keep them in `public/` and link them with a plain `<link rel=\"icon\">` instead of the image pipeline.","Automate a pre-commit/build check that flags unsupported extensions in `src/assets`."],"exampleFix":"# before\nimport icon from './favicon.ico';\n\n# after — convert once, then import\nconvert favicon.ico favicon.png","handlingStrategy":"validation","validationCode":"import { extname } from 'node:path';\nconst VALID = ['jpeg', 'jpg', 'png', 'tiff', 'webp', 'gif', 'svg', 'avif'];\n// CI script: scan imported image assets for unsupported extensions\nfor (const file of imageFiles) {\n  const ext = extname(file).slice(1).toLowerCase();\n  if (!VALID.includes(ext)) {\n    throw new Error(`Unsupported image format .${ext}: ${file}`);\n  }\n}","typeGuard":"const SUPPORTED_IMAGE_EXTENSIONS = ['jpeg', 'jpg', 'png', 'tiff', 'webp', 'gif', 'svg', 'avif'];\nconst isSupportedImageFile = (path: string): boolean =>\n  SUPPORTED_IMAGE_EXTENSIONS.includes(path.split('.').pop()?.toLowerCase() ?? '');","tryCatchPattern":null,"preventionTips":["Convert ico/bmp/heic assets once at design handoff, not at build time.","Keep favicons and other verbatim files in public/, outside the import pipeline.","Add a lint/CI scan for unsupported extensions under src/."],"tags":["images","image-formats","esm-import"],"backgroundTag":"unsupported-image-format","analyzedSha":"e294953aa8aadd98d5be92e60a03037b05dbdfd4","analyzedAt":"2026-08-18T18:48:03.901Z","contentChangedAt":"2026-08-18T18:48:03.901Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}