{"record":{"id":"6bfb34e0357ca9c0","repo":"withastro/astro","slug":"unsupported-image-format-options-format","errorCode":null,"errorMessage":"Unsupported image format \"${options.format}\"","messagePattern":"Unsupported image format \"(.+?)\"","errorType":"validation","errorClass":"AstroError","httpStatus":null,"severity":"error","filePath":"packages/integrations/netlify/src/image-service.ts","lineNumber":57,"sourceCode":"\n\t\tif (options.format) query.set('fm', options.format);\n\t\tif (options.width) query.set('w', `${options.width}`);\n\t\tif (options.height) query.set('h', `${options.height}`);\n\t\tif (options.quality) query.set('q', `${options.quality}`);\n\t\tif (options.fit) {\n\t\t\tconst netlifyFit = FIT_MAP[options.fit];\n\t\t\tif (netlifyFit) query.set('fit', netlifyFit);\n\t\t}\n\n\t\treturn `/.netlify/images?${query}`;\n\t},\n\tgetHTMLAttributes: baseService.getHTMLAttributes,\n\tgetSrcSet: baseService.getSrcSet,\n\tvalidateOptions(options) {\n\t\tverifyOptions(options);\n\n\t\tif (options.format && !SUPPORTED_FORMATS.includes(options.format)) {\n\t\t\tthrow new AstroError(\n\t\t\t\t`Unsupported image format \"${options.format}\"`,\n\t\t\t\t`Use one of ${SUPPORTED_FORMATS.join(', ')} instead.`,\n\t\t\t);\n\t\t}\n\n\t\tif (options.quality) {\n\t\t\toptions.quality =\n\t\t\t\ttypeof options.quality === 'string' ? QUALITY_NAMES[options.quality] : options.quality;\n\t\t\tif (options.quality < 1 || options.quality > 100) {\n\t\t\t\tthrow new AstroError(\n\t\t\t\t\t`Invalid quality for picture \"${options.src}\"`,\n\t\t\t\t\t'Quality needs to be between 1 and 100.',\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\t\treturn options;\n\t},\n};","sourceCodeStart":39,"sourceCodeEnd":75,"githubUrl":"https://github.com/withastro/astro/blob/52e6c34790cc8ac4e69e6135ace06049867e5c4a/packages/integrations/netlify/src/image-service.ts#L39-L75","documentation":"The Netlify adapter installs an external image service that defers resizing to Netlify's /.netlify/images endpoint, which only outputs avif, jpg, png, and webp (SUPPORTED_FORMATS in image-service.ts). validateOptions runs for every Image/getImage call and throws this AstroError when options.format is outside that list.","triggerScenarios":"Passing format: 'jpeg' (the list uses 'jpg'), or format: 'svg', 'gif', 'tiff' etc. to the Image component or getImage() while the Netlify adapter's image service is active.","commonSituations":"Migrating from Astro's default sharp service (which supports more output formats) to the Netlify adapter; typing 'jpeg' out of habit; attempting to convert a raster image into SVG.","solutions":["Use one of avif, jpg, png, webp","Spell JPEG as 'jpg', not 'jpeg'","For SVG, import/serve the SVG directly instead of transforming another image to SVG","Omit format to keep the source format when it is already supported"],"exampleFix":"// before\n<Image src={hero} format=\"jpeg\" width={828} alt=\"hero\" />\n// after\n<Image src={hero} format=\"jpg\" width={828} alt=\"hero\" />","handlingStrategy":"validation","validationCode":"const NETLIFY_FORMATS = ['avif', 'jpg', 'png', 'webp'] as const;\nconst format = NETLIFY_FORMATS.includes(options.format as any) ? options.format : undefined;\nconst img = await getImage({ ...options, format });","typeGuard":"const NETLIFY_FORMATS = ['avif', 'jpg', 'png', 'webp'] as const;\ntype NetlifyFormat = (typeof NETLIFY_FORMATS)[number];\nfunction isNetlifyFormat(f: string): f is NetlifyFormat {\n  return (NETLIFY_FORMATS as readonly string[]).includes(f);\n}","tryCatchPattern":"import { AstroError } from 'astro/errors';\ntry {\n  return await getImage(options);\n} catch (err) {\n  if (err instanceof AstroError && err.message.startsWith('Unsupported image format')) {\n    return await getImage({ ...options, format: undefined });\n  }\n  throw err;\n}","preventionTips":["Use 'jpg', never 'jpeg', when the Netlify adapter is active","Centralize image options in one helper so the format list is enforced in one place","Remember installing the adapter swaps the image service and its format support"],"tags":["netlify","image-service","format","validate-options"],"backgroundTag":"unsupported-image-format","analyzedSha":"52e6c34790cc8ac4e69e6135ace06049867e5c4a","analyzedAt":"2026-08-18T18:48:03.901Z","contentChangedAt":"2026-08-18T18:48:03.901Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}