How to Fix LocalImageUsedWrongly: src Cannot Be a String Filepath

You get LocalImageUsedWrongly when you give Astro’s <Image /> a typed path, like src="../assets/photo.png". Astro can’t use a path in quotes. Import the picture at the top of the file instead. Then pass it in with curly brackets, like src={photo}.

Why it happens

Astro’s <Image /> does smart work. It finds how big the picture is. It makes a small, fast copy. To do that, it has to read the file when it builds your site.

Astro can only read pictures you import. A path in quotes is just words. Astro does not know it points to a file.

We made this page in a fresh Astro 7.4 project. The file is really there:

---
import { Image } from 'astro:assets';
---
<h1>About me</h1>
<Image src="../assets/astro.svg" alt="The Astro logo" />

Then we ran the build. Here is the error, with the long file paths cut out:

$ npm run build
[LocalImageUsedWrongly] `Image`'s and `getImage`'s `src` parameter must be an imported image or a URL, it cannot be a string filepath. Received `../assets/astro.svg`.
Hint:
  If you want to use an image from your `src` folder, you need to either import it or if the image is coming from a content collection, use the image() schema helper https://docs.astro.build/en/guides/images/#images-in-content-collections. See https://docs.astro.build/en/reference/modules/astro-assets/#src-required for more information on the `src` property.
Error reference:
  https://docs.astro.build/en/reference/errors/local-image-used-wrongly/

That’s a lot of words. The fix is short.

How to fix it

1. Find the line. Look for <Image with src="..." in quotes. The error shows the path. It comes right after the word Received.
2. Import the picture. At the top of the file, inside the --- lines, add an import. Give the picture a short name, like logo.
3. Use the name in curly brackets. Change src="../assets/astro.svg" to src={logo}.

Here is our page after the fix:

---
import { Image } from 'astro:assets';
import logo from '../assets/astro.svg';
---
<h1>About me</h1>
<Image src={logo} alt="The Astro logo" />

We built again, and it worked. Then we looked in the built page, dist/about/index.html. Astro had made this tag. It even added the width and height:

<img src="/_astro/astro.Dm8K3lV8_28Kit4.svg" alt="The Astro logo" loading="lazy" decoding="async" width="115" height="48">

Still stuck?

• Read the official LocalImageUsedWrongly page in the Astro docs.
• Paste the page file and the error into an AI. Our guide on fixing Astro errors with AI shows what to say.
• Ask in our community.

Where to go next

• How to add images to Astro shows the full way to add pictures.
• How to fix the most common Astro errors for other errors beginners hit.