{"record":{"id":"8fd6d46e9be68dd6","repo":"withastro/astro","slug":"localimageusedwrongly","errorCode":"LocalImageUsedWrongly","errorMessage":"`Image`'s and `getImage`'s `src` parameter must be an imported image or a URL, it cannot be a string filepath. Received `${imageFilePath}`.","messagePattern":"`Image`'s and `getImage`'s `src` parameter must be an imported image or a URL, it cannot be a string filepath\\. Received `(.+?)`\\.","errorType":"exception","errorClass":"AstroError","httpStatus":null,"severity":"error","filePath":"packages/astro/src/assets/services/service.ts","lineNumber":164,"sourceCode":"\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),\n\t\t\t});\n\t\t}\n\n\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,","sourceCodeStart":146,"sourceCodeEnd":182,"githubUrl":"https://github.com/withastro/astro/blob/d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca/packages/astro/src/assets/services/service.ts#L146-L182","documentation":"Thrown by verifyOptions() when src is a string that is not ESM-imported and looks like a local filesystem path. The check fires when the string starts with '/@fs/' or is not remote and does not start with '/'. Passing an absolute/relative filesystem path instead of an import or a URL is rejected.","triggerScenarios":"Calling the service with options.src equal to '/@fs/abs/path/img.png', a relative path like 'assets/img.png', or 'C:/images/img.png' on Windows — i.e. a local path used where an import or a public-rooted/remote URL is required.","commonSituations":"User writes <Image src='/path/to/local.png' /> intending a local image instead of `import img from './img.png'`, or pastes an absolute disk path. Also a stray '/@fs/' URL leaking from dev tooling.","solutions":["Import local images as ESM assets: import img from './img.png'; then <Image src={img} />.","Place public images under public/ and reference them by root-relative URL starting with '/' (e.g. '/img.png').","For remote images use the full https:// URL.","Never pass raw disk paths or '/@fs/' URLs to Image/getImage."],"exampleFix":"// before\n<Image src='/@fs/home/user/proj/img.png' />\n\n// after\nimport img from '../assets/img.png';\n<Image src={img} />","handlingStrategy":"validation","validationCode":"function isLocalDiskPath(src: string): boolean {\n  return src.startsWith('/@fs/') || (!/^https?:\\/\\//.test(src) && !src.startsWith('/'));\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Import local images as ESM assets, never reference disk paths.","Place public images under public/ and use root-relative URLs.","Reject '/@fs/' URLs from leaking into production builds."],"tags":["images","esm","paths","api-misuse"],"backgroundTag":null,"analyzedSha":"d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca","analyzedAt":"2026-08-12T13:37:29.035Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}