{"record":{"id":"97cdd57de43ebe6b","repo":"withastro/astro","slug":"expectedimage-97cdd5","errorCode":"ExpectedImage","errorMessage":"Expected `src` property for `getImage` or `<Image />` to be either an ESM imported image or a string with the path of a remote image. Received `${src}` (type: `${typeofOptions}`).\\n\\nFull serialized options received: `${fullOptions}`.","messagePattern":"Expected `src` property for `getImage` or `<Image />` to be either an ESM imported image or a string with the path of a remote image\\. Received `(.+?)` \\(type: `(.+?)`\\)\\.\\\\n\\\\nFull serialized options received: `(.+?)`\\.","errorType":"exception","errorClass":"AstroError","httpStatus":null,"severity":"error","filePath":"packages/astro/src/assets/services/service.ts","lineNumber":148,"sourceCode":"}\n\nexport type BaseServiceTransform = {\n\tsrc: string;\n\twidth?: number;\n\theight?: number;\n\tformat?: string;\n\tquality?: string | null;\n\tfit?: ImageFit;\n\tposition?: string;\n\tbackground?: string;\n};\n\nconst sortNumeric = (a: number, b: number) => a - b;\n\nexport function verifyOptions(options: ImageTransform): void {\n\t// `src` is missing or is `undefined`.\n\tif (!options.src || (!isRemoteImage(options.src) && !isESMImportedImage(options.src))) {\n\t\tthrow new AstroError({\n\t\t\t...AstroErrorData.ExpectedImage,\n\t\t\tmessage: AstroErrorData.ExpectedImage.message(\n\t\t\t\tJSON.stringify(options.src),\n\t\t\t\ttypeof options.src,\n\t\t\t\tJSON.stringify(options, (_, v) => (v === undefined ? null : v)),\n\t\t\t),\n\t\t});\n\t}\n\n\tif (!isESMImportedImage(options.src)) {\n\t\t// User passed an `/@fs/` path or a filesystem path instead of the full image.\n\t\tif (\n\t\t\toptions.src.startsWith('/@fs/') ||\n\t\t\t(!isRemotePath(options.src) && !options.src.startsWith('/'))\n\t\t) {\n\t\t\tthrow new AstroError({\n\t\t\t\t...AstroErrorData.LocalImageUsedWrongly,\n\t\t\t\tmessage: AstroErrorData.LocalImageUsedWrongly.message(options.src),","sourceCodeStart":130,"sourceCodeEnd":166,"githubUrl":"https://github.com/withastro/astro/blob/d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca/packages/astro/src/assets/services/service.ts#L130-L166","documentation":"Thrown by verifyOptions() in the base image service when src is falsy or is neither a remote-image string nor an ESM-imported image. The guard `!options.src || (!isRemoteImage && !isESMImportedImage)` rejects empty strings, null, numbers, or any value that is not a string and not an object with import metadata.","triggerScenarios":"Calling the image service with verifyOptions(options) where options.src is '', null, 0, false, a plain object lacking import metadata, a number, or any non-string/non-ImageMetadata value. isRemoteImage is true only for strings; isESMImportedImage is true only for objects/functions with import shape.","commonSituations":"An empty image URL pulled from a CMS field, a broken import that resolved to undefined-coerced-to-string, passing a Buffer/File instead of an import, or a dynamic src that evaluated to a non-image value.","solutions":["Ensure src is either an ESM-imported asset or a non-empty remote URL string.","Guard upstream: if (!src) return null; before rendering.","Re-check that imported assets resolve (no broken paths) so src isn't ''.","If passing an object, pass the Astro import metadata, not a raw buffer."],"exampleFix":"// before\n<Image src={entry.data.maybeMissingUrl} />\n\n// after\n{entry.data.maybeMissingUrl && <Image src={entry.data.maybeMissingUrl} width={800} height={600} />}","handlingStrategy":"validation","validationCode":"import { isESMImportedImage, isRemoteImage } from 'astro/assets/utils';\nfunction isValidSrc(src: unknown): boolean {\n  return (typeof src === 'string' && src.length > 0) || isESMImportedImage(src as any);\n}","typeGuard":"function isValidImageSrc(src: unknown): src is string | ImageMetadata {\n  return (typeof src === 'string' && src.length > 0) || (typeof src === 'object' && src !== null && 'fsPath' in src);\n}","tryCatchPattern":null,"preventionTips":["Never pass empty/null src values; guard upstream.","Validate CMS fields before rendering.","Use ESM imports or full URLs only."],"tags":["images","validation","service"],"backgroundTag":null,"analyzedSha":"d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca","analyzedAt":"2026-08-12T13:37:29.035Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}