withastro/astro · error · Error

Failed to parse image reference

Error message

Failed to parse image reference: ${imagePath}

What it means

When a markdown/MDX entry is rendered, Astro replaces the internal __ASTRO_IMAGE_ markers emitted by its remark image pipeline with optimized images. It first pre-loads every referenced image (JSON-decodes the marker, resolves a local path against the asset-imports map or treats it as a remote URL, then calls getImage). Any failure inside that block is rethrown as this generic error, hiding the original cause.

Solutions

1. Identify the failing entry from the stack/rendered file and inspect every image reference in that markdown.
2. Rename image files to remove quotes, apostrophes, and unusual characters, then update the references.
3. Verify each referenced local image exists on disk relative to the entry file.
4. For remote images, confirm the domain is allow-listed in the image config and reachable.
5. Temporarily disable custom remark/rehype plugins that rewrite image nodes to isolate the cause.

Example fix

<!-- before: content/blog/post.md references an awkward filename -->
![Cover](../../assets/it's a "cover".png)

<!-- after: rename the asset and reference it plainly -->
![Cover](../../assets/cover.png)

// Pre-build check: every local image referenced by markdown must exist
import { readFile } from 'node:fs/promises';
import { existsSync } from 'node:fs';
import { dirname, join, relative, resolve } from 'node:path';

for (const file of await collectMarkdown('src/content')) {
  const text = await readFile(file, 'utf8');
  for (const [, rel] of text.matchAll(/!\[[^\]]*\]\(([^)]+)\)/g)) {
    if (/^(https?:|data:)/.test(rel)) continue;
    const target = resolve(dirname(file), rel.split(' ')[0]);
    if (!existsSync(target)) console.error(`missing image ${rel} in ${file}`);
  }
}

// While looping a collection, isolate which entry has the bad reference
for (const entry of await getCollection('docs')) {
  try {
    await render(entry);
  } catch (e) {
    if (e instanceof Error && e.message.startsWith('Failed to parse image reference')) {
      console.error(`bad image reference in ${entry.id}`);
      continue;
    }
    throw e;
  }
}

When it happens

Trigger: An image whose serialized __ASTRO_IMAGE_ attribute fails JSON.parse (quotes or apostrophes in filenames serialized as entities); a relative image path absent from the astro:asset-imports map (file missing, moved, or outside the project); a remote image for which getImage throws (unreachable host, domain not allow-listed, invalid dimensions).

Common situations: Image filenames containing apostrophes or quotes (e.g. it's.png); deleting or renaming images still referenced by old content; remote images not configured under images.domains / images.remotePatterns; custom remark plugins injecting malformed image nodes; version upgrades that changed the marker encoding.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• not applied.
• Could not resolve image
• ImageNotFound
• InvalidContentEntrySlugError
• InvalidFrontmatterInjectionError

AI-assisted analysis of withastro/astro@e294953aa8 (2026-08-18). Data as JSON: /api/errors/ca3e9778c85e0da4. Report an issue: GitHub.

Appendix: source

Thrown at packages/astro/src/content/runtime.ts:503

			let image: GetImageResult;
			if (URL.canParse(decodedImagePath.src)) {
				// Remote image, pass through without resolving import
				// We know we should resolve this remote image because either:
				// 1. It was collected with the remark-collect-images plugin, which respects the astro image configuration,
				// 2. OR it was manually injected by another plugin, and we should respect that.
				image = await getImage(decodedImagePath);
			} else {
				const id = imageSrcToImportId(decodedImagePath.src, fileName);

				const imported = imageAssetMap.get(id);
				if (!id || imageObjects.has(id) || !imported) {
					continue;
				}
				image = await getImage({ ...decodedImagePath, src: imported });
			}
			imageObjects.set(imagePath, image);
		} catch {
			throw new Error(`Failed to parse image reference: ${imagePath}`);
		}
	}

	return html.replaceAll(CONTENT_LAYER_IMAGE_REGEX, (full, imagePath) => {
		const image = imageObjects.get(imagePath);

		if (!image) {
			return full;
		}

		const { index, ...attributes } = image.attributes;

		return Object.entries({
			...attributes,
			src: image.src,
			// An empty `srcset` is invalid HTML, so only emit it when there are
			// actual candidates. This matches `vite-plugin-markdown/images.ts`.
			...(image.srcSet.values.length > 0 ? { srcset: image.srcSet.attribute } : {}),

View on GitHub (pinned to e294953aa8)