Astro shows “Image not found” when it tries to load an image at a path that doesn’t exist. The message asks “Does it exist?” and the hint names the usual reason: “This is often caused by a typo in the image path.” Check the spelling and letter case of the file name, then check the path is relative to the right file.
Key Takeaways
- Paths in Markdown and frontmatter are relative to the Markdown file, not the project root.
- Letter case matters on Linux build servers even when your Mac ignores it.
- Images referenced from
public/use a root path (/images/x.png) and aren’t imported.- Renamed or moved files break every path pointing at them; search for the old name.
Check 1: spelling and case
Hero.JPG and hero.jpg are the same file on macOS’s default file system but different files on Linux, where most CI and hosting builds run. A build that passes locally and fails on the host with “Image not found” is almost always a case mismatch. List the real name:
ls src/assets/ | grep -i heroRename to lowercase and update references. A consistent lowercase, hyphenated naming rule prevents repeats.
Check 2: relative to which file?
In a content collection, frontmatter paths are resolved from the Markdown file’s folder:
src/content/blog/launch/index.md
src/content/blog/launch/cover.jpg# src/content/blog/launch/index.md
cover: ./cover.jpgIf the image is in src/assets/, the path climbs up from the post:
cover: ../../../assets/covers/launch.jpgKeeping each post’s images next to the post (a folder per post) avoids long fragile paths.
The same applies to body images:  is relative to the Markdown file.
Check 3: src/ or public/?
| Location | Reference as | Optimised? |
|---|---|---|
src/assets/hero.jpg |
import hero from '../assets/hero.jpg' |
Yes |
public/images/hero.jpg |
"/images/hero.jpg" |
No |
Mixing the two (for example "/src/assets/hero.jpg" as a string, or importing from public/) leads to this error or to Local images must be imported.
Check 4: the file was moved or deleted
Search for references after any rename:
grep -rn "old-name.jpg" src/Check 5: images from a CMS
For remote URLs, “not found” can mean the CMS returned 404 at build time. Open the URL in a browser. If it’s missing upstream, the build will keep failing until the CMS entry is fixed or the image is removed. Remote images also need allowed domains; see Remote image is not allowed.
For how Astro processes images, see the Astro performance guide and the Astro content collections guide for frontmatter images. The official entry is in the Astro error reference.
FAQ
Why does the build fail on Netlify or Cloudflare but work locally?
Usually letter case: Linux file systems are case-sensitive, and macOS by default is not.
Can I make Astro skip missing images instead of failing?
Not for imported or schema-validated images, which is deliberate. Make the field optional in the schema if some entries genuinely have no image, and render conditionally.