{"record":{"id":"ca3e9778c85e0da4","repo":"withastro/astro","slug":"failed-to-parse-image-reference-imagepath","errorCode":null,"errorMessage":"Failed to parse image reference: ${imagePath}","messagePattern":"Failed to parse image reference: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/astro/src/content/runtime.ts","lineNumber":492,"sourceCode":"\t\t\tlet image: GetImageResult;\n\t\t\tif (URL.canParse(decodedImagePath.src)) {\n\t\t\t\t// Remote image, pass through without resolving import\n\t\t\t\t// We know we should resolve this remote image because either:\n\t\t\t\t// 1. It was collected with the remark-collect-images plugin, which respects the astro image configuration,\n\t\t\t\t// 2. OR it was manually injected by another plugin, and we should respect that.\n\t\t\t\timage = await getImage(decodedImagePath);\n\t\t\t} else {\n\t\t\t\tconst id = imageSrcToImportId(decodedImagePath.src, fileName);\n\n\t\t\t\tconst imported = imageAssetMap.get(id);\n\t\t\t\tif (!id || imageObjects.has(id) || !imported) {\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\timage = await getImage({ ...decodedImagePath, src: imported });\n\t\t\t}\n\t\t\timageObjects.set(imagePath, image);\n\t\t} catch {\n\t\t\tthrow new Error(`Failed to parse image reference: ${imagePath}`);\n\t\t}\n\t}\n\n\treturn html.replaceAll(CONTENT_LAYER_IMAGE_REGEX, (full, imagePath) => {\n\t\tconst image = imageObjects.get(imagePath);\n\n\t\tif (!image) {\n\t\t\treturn full;\n\t\t}\n\n\t\tconst { index, ...attributes } = image.attributes;\n\n\t\treturn Object.entries({\n\t\t\t...attributes,\n\t\t\tsrc: image.src,\n\t\t\tsrcset: image.srcSet.attribute,\n\t\t\t// This attribute is used by the toolbar audit\n\t\t\t...(import.meta.env.DEV ? { 'data-image-component': 'true' } : {}),","sourceCodeStart":474,"sourceCodeEnd":510,"githubUrl":"https://github.com/withastro/astro/blob/d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca/packages/astro/src/content/runtime.ts#L474-L510","documentation":"Thrown as a plain Error (no AstroError code) from updateImageReferencesInBody when processing a collected image reference embedded in rendered HTML. The wrapped try-block covers JSON.parse of the decoded attribute, imageSrcToImportId resolution, map lookup, and getImage() — any failure there surfaces as this generic message with the offending imagePath.","triggerScenarios":"An HTML attribute matching CONTENT_LAYER_IMAGE_REGEX (__ASTRO_IMAGE_=\"...\") whose value fails to JSON.parse after entity decoding, or whose resolved src/import id cannot be looked up in imageAssetMap, or for which getImage() rejects.","commonSituations":"A remark/rehype plugin injecting malformed image metadata; image import id present in rendered HTML but missing from the asset map (stale .astro cache); remote image URL that fails getImage validation; manually-injected HTML with the reserved __ASTRO_IMAGE_ attribute; corrupt build cache after partial sync.","solutions":["Clear the content cache and rebuild: rm -rf .astro then re-run sync/build.","Inspect the imagePath value in the error to see whether it's malformed JSON or a missing import id.","Audit custom remark/rehype plugins that inject images to ensure they emit well-formed metadata.","Verify the referenced image file exists and is importable from the entry's filePath."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Validate imagePath is JSON-decodable before render\nfunction isValidImageRef(raw: string) {\n  try { const o = JSON.parse(raw.replace(/&(?:#x22|quot);/g,'\"').replace(/&(?:#x27|apos);/g,\"'\")); return o && typeof o.src === 'string'; } catch { return false; }\n}","typeGuard":"const looksLikeImageRef = (s: string) => s.startsWith('{') && s.endsWith('}') && /\"src\"\\s*:/.test(s);","tryCatchPattern":"try {\n  await updateImageReferencesInBody(html, fileName);\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('Failed to parse image reference')) {\n    // clear cache and rebuild, or strip malformed image refs from source\n  }\n  throw e;\n}","preventionTips":["Keep .astro cache clean before content sync.","Audit custom remark/rehype plugins that inject images.","Ensure referenced image files exist and are importable."],"tags":["content-collections","image","rendering","remark","cache"],"backgroundTag":null,"analyzedSha":"d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca","analyzedAt":"2026-08-12T13:37:29.035Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}