{"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/d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca/packages/integrations/netlify/src/image-service.ts#L39-L75","documentation":"The Netlify image service's `validateOptions` rejects any `format` not in `['avif','jpg','png','webp']`. This is narrower than Astro's base set (no `gif`, `svg` output, etc.) because Netlify's Image CDN only supports those four output formats. It throws `AstroError` with a hint listing the allowed formats.","triggerScenarios":"Configuring an image/picture with `format: 'gif'`, `'jpeg'` (note: it's `jpg` not `jpeg`), `'svg'` output, or any unsupported value while the Netlify adapter is active. Setting `image.format` globally in config to something Netlify rejects.","commonSituations":"Migrating from sharp/squoosh default service to Netlify and keeping a previously-valid format. Using `'jpeg'` instead of `'jpg'`. Configuring a picture element with an explicit unsupported format.","solutions":["Use one of: `avif`, `jpg`, `png`, `webp`.","If you need `jpeg`, spell it as `jpg`.","Switch the image service back to `'astro/assets/services/sharp'` or `squoosh'` if you require other formats.","Remove the explicit `format` to let the service pick a supported default."],"exampleFix":"// before\nimport { getImage } from 'astro:assets';\nawait getImage({ src, format: 'jpeg' });\n\n// after\nawait getImage({ src, format: 'jpg' });","handlingStrategy":"validation","validationCode":"const NETLIFY_FORMATS = ['avif', 'jpg', 'png', 'webp'] as const;\nfunction isNetlifyFormat(f: string): f is typeof NETLIFY_FORMATS[number] {\n  return (NETLIFY_FORMATS as readonly string[]).includes(f);\n}\nif (options.format === 'jpeg') options.format = 'jpg';\nif (options.format && !isNetlifyFormat(options.format)) {\n  throw new Error(`Unsupported format; use one of ${NETLIFY_FORMATS.join(', ')}`);\n}","typeGuard":"function isSupportedFormat(f: unknown): f is 'avif' | 'jpg' | 'png' | 'webp' {\n  return f === 'avif' || f === 'jpg' || f === 'png' || f === 'webp';\n}","tryCatchPattern":null,"preventionTips":["Restrict formats to `avif|jpg|png|webp` when using Netlify's image service.","Normalize `jpeg` → `jpg` upstream.","Switch image service if you need formats Netlify doesn't support."],"tags":["netlify","images","assets","configuration"],"backgroundTag":null,"analyzedSha":"d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca","analyzedAt":"2026-08-12T13:37:29.035Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}