{"record":{"id":"6e06a4c56d530144","repo":"withastro/astro","slug":"could-not-resolve-image-json-stringify-node-attr","errorCode":null,"errorMessage":"Could not resolve image ${JSON.stringify(node.attributes.src)} from ${JSON.stringify(ctx.filePath)}. Does the file exist?","messagePattern":"Could not resolve image (.+?) from (.+?)\\. Does the file exist\\?","errorType":"exception","errorClass":"MarkdocError","httpStatus":null,"severity":"error","filePath":"packages/integrations/markdoc/src/content-entry-type.ts","lineNumber":337,"sourceCode":"\t\t\t\t\t\t? undefined\n\t\t\t\t\t\t: (opts: Parameters<typeof ctx.pluginContext.emitFile>[0]) =>\n\t\t\t\t\t\t\t\temitClientAsset(ctx.pluginContext, opts);\n\t\t\t\t\tconst src = await emitImageMetadata(resolved.id, fileEmitter);\n\n\t\t\t\t\tconst fsPath = resolved.id;\n\n\t\t\t\t\tif (src) {\n\t\t\t\t\t\t// We cannot track images in Markdoc, Markdoc rendering always strips out the proxy. As such, we'll always\n\t\t\t\t\t\t// assume that the image is referenced elsewhere, to be on safer side.\n\t\t\t\t\t\tif (ctx.astroConfig.output === 'static') {\n\t\t\t\t\t\t\tif (globalThis.astroAsset.referencedImages)\n\t\t\t\t\t\t\t\tglobalThis.astroAsset.referencedImages.add(fsPath);\n\t\t\t\t\t\t}\n\n\t\t\t\t\t\tnode.attributes[attributeName] = { ...src, fsPath };\n\t\t\t\t\t}\n\t\t\t\t} else {\n\t\t\t\t\tthrow new MarkdocError({\n\t\t\t\t\t\tmessage: `Could not resolve image ${JSON.stringify(\n\t\t\t\t\t\t\tnode.attributes.src,\n\t\t\t\t\t\t)} from ${JSON.stringify(ctx.filePath)}. Does the file exist?`,\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t} else if (isComponent) {\n\t\t\t\t// If the user is using the {% image %} tag, always pass the `src` attribute as `__optimizedSrc`, even if it's an external URL or absolute path.\n\t\t\t\t// That way, the component can decide whether or not to optimize it.\n\t\t\t\tnode.attributes[attributeName] = node.attributes.src;\n\t\t\t}\n\t\t}\n\t\tawait emitOptimizedImages(node.children, ctx);\n\t}\n}\n\nfunction shouldOptimizeImage(src: string) {\n\t// Optimize anything that is NOT external or an absolute path to `public/`\n\treturn !isValidUrl(src) && !src.startsWith('/');","sourceCodeStart":319,"sourceCodeEnd":355,"githubUrl":"https://github.com/withastro/astro/blob/d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca/packages/integrations/markdoc/src/content-entry-type.ts#L319-L355","documentation":"When resolving an image node in Markdoc, the integration tries to compute a resolved source via the Astro image pipeline. If resolution returns nothing (no `src`), it throws `MarkdocError` showing the unresolved `node.attributes.src` and the originating `ctx.filePath`. Static-output builds also add the path to `globalThis.astroAsset.referencedImages` on success.","triggerScenarios":"Using `{% image src=\"/missing.png\" / %}` or `{% image src=\"./nope.jpg\" / %}` where the image cannot be resolved by the Astro asset service from the Markdoc file's location. Remote image that fails fetch. Image import path that does not resolve through Vite.","commonSituations":"Image file missing or moved. Wrong relative path from the `.mdoc`. Image outside the project's allowed directories. Non-existent remote URL during build.","solutions":["Confirm the image file exists at the path used in `src`.","For local images use a relative path from the `.mdoc` file (e.g. `src=\"../../assets/hero.png\"`).","For remote images verify the URL is reachable at build time.","Ensure the asset lives under a directory covered by Vite's `fs.allow`."],"exampleFix":"{% image src=\"../../assets/hero.png\" alt=\"Hero\" / %}","handlingStrategy":"validation","validationCode":"import { pathExists } from 'fs-extra';\nasync function imageSourceOk(src: string, baseDir: string) {\n  if (/^https?:\\/\\//.test(src)) return true;\n  return pathExists(path.resolve(baseDir, src));\n}","typeGuard":"function isResolvableImageSrc(src: unknown): src is string {\n  return typeof src === 'string' && src.length > 0;\n}","tryCatchPattern":"try {\n  await resolveImage(node, ctx);\n} catch (e) {\n  ctx.logger?.error?.(`Image ${node.attributes.src} could not be resolved from ${ctx.filePath}`);\n  throw e;\n}","preventionTips":["Use relative paths from the `.mdoc` for local images.","Verify remote image URLs are reachable at build time.","Keep image assets under Vite `fs.allow`."],"tags":["markdoc","images","assets","build"],"backgroundTag":null,"analyzedSha":"d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca","analyzedAt":"2026-08-12T13:37:29.035Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}