{"record":{"id":"84f47040f1116059","repo":"withastro/astro","slug":"vercel-image-optimization-requires-at-least-one-si","errorCode":null,"errorMessage":"Vercel Image Optimization requires at least one size to be configured.","messagePattern":"Vercel Image Optimization requires at least one size to be configured\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/integrations/vercel/src/image/shared.ts","lineNumber":112,"sourceCode":"\t\t\t},\n\t\t};\n\t}\n\n\treturn {};\n}\n\nexport function sharedValidateOptions(\n\toptions: ImageTransform,\n\tserviceConfig: Record<string, any>,\n\tmode: 'development' | 'production',\n) {\n\tconst vercelImageOptions = serviceConfig as VercelImageConfig;\n\n\tif (\n\t\tmode === 'development' &&\n\t\t(!vercelImageOptions.sizes || vercelImageOptions.sizes.length === 0)\n\t) {\n\t\tthrow new Error('Vercel Image Optimization requires at least one size to be configured.');\n\t}\n\n\tconst configuredWidths = vercelImageOptions.sizes.sort((a, b) => a - b);\n\n\t// The logic for finding the perfect width is a bit confusing, here it goes:\n\t// For images where no width has been specified:\n\t// - For local, imported images, fall back to nearest width we can find in our configured\n\t// - For remote images, that's an error, width is always required.\n\t// For images where a width has been specified:\n\t// - If the width that the user asked for isn't in `sizes`, then fall back to the nearest one, but save the width\n\t// \tthe user asked for so we can put it on the `img` tag later.\n\t// - Otherwise, just use as-is.\n\t// The end goal is:\n\t// - The size on the page is always the one that the user asked for or the base image's size\n\t// - The actual size of the image file is always one of `sizes`, either the one that the user asked for or the nearest to it\n\tif (!options.width) {\n\t\tconst src = options.src;\n\t\tif (isESMImportedImage(src)) {","sourceCodeStart":94,"sourceCodeEnd":130,"githubUrl":"https://github.com/withastro/astro/blob/d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca/packages/integrations/vercel/src/image/shared.ts#L94-L130","documentation":"Thrown by the Vercel image service's `sharedValidateOptions` when, in development mode, the configured `image.service.config.sizes` array is empty or absent. Vercel Image Optimization serves only a discrete set of widths, so at least one must be declared.","triggerScenarios":"Configuring `image: { service: { entrypoint: '@astrojs/vercel/image-service' } }` without a `config: { sizes: [...] }`. Setting `sizes: []`. Running in `dev` (the guard is `mode === 'development'`).","commonSituations":"Following a tutorial that omits the sizes config. Copying a production-only config into a dev environment. Expecting a default sizes list that does not exist.","solutions":["Add `sizes` to the image service config: `image: { service: { entrypoint: '@astrojs/vercel/image-service', config: { sizes: [320, 640, 1024] } } }`.","Provide at least one width even for local dev; Vercel requires an explicit discrete set.","Verify the config is nested under `service.config`, not directly under `image`."],"exampleFix":"// before\nexport default defineConfig({\n  image: { service: { entrypoint: '@astrojs/vercel/image-service' } },\n});\n// after\nexport default defineConfig({\n  image: {\n    service: {\n      entrypoint: '@astrojs/vercel/image-service',\n      config: { sizes: [320, 640, 1024, 1920] },\n    },\n  },\n});","handlingStrategy":"validation","validationCode":"const sizes = serviceConfig?.sizes;\nif (mode === 'development' && (!Array.isArray(sizes) || sizes.length === 0)) {\n  throw new Error('Configure image.service.config.sizes with at least one width.');\n}","typeGuard":"function hasValidSizes(cfg: unknown): cfg is { sizes: number[] } {\n  return Array.isArray((cfg as any)?.sizes) && (cfg as any).sizes.length > 0;\n}","tryCatchPattern":null,"preventionTips":["Always set `sizes` under `image.service.config` when using the Vercel image service.","Add a config-validation unit test in CI.","Keep a documented default sizes list per project."],"tags":["vercel","image-optimization","config","development"],"backgroundTag":null,"analyzedSha":"d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca","analyzedAt":"2026-08-12T13:37:29.035Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}