Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

A background image in CSS does not load in Vite

Error404 (Not Found) for an image or font requested through url() in CSS

Short answer

Vite treats url() in CSS like an import: relative paths resolve from the CSS file, absolute paths from the project root during dev, and files in public are served at the site root. A path that matches none of these, or a deploy under a subfolder with the wrong base, returns a 404 for the image.

  • Applies to Vite 7, Vite 8, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Open DevTools, Network tab, filter by Img or Font, and read the URL of the failed request. Compare it with where the file really sits.

    ls public src/assets
    grep -rn "url(" src --include=*.css --include=*.scss
  2. 2Match what you see, then jump to its fix

    1. 1The failed request URL contains the folder name public, or the CSS path contains public/The path points into public with the wrong formFix
    2. 2The file exists under src/assets but the build cannot find it, or the URL contains the wrong folderA relative path is written from the wrong folderFix
    3. 3Images load in dev and 404 after deploy to https://host/my-app/The app is served from a subfolder but base is still /Fix

What does the error look like?

  • 404 (Not Found) for an image or font requested through url() in CSS
  • Background image or web font referenced in url() does not show

Cause 1 of 3

The path points into public with the wrong form

1Check

Files in the public directory are not processed. Vite serves them at / in dev and copies them to the root of the output folder, so the CSS has to refer to them with a root-absolute path.

ls public
grep -rn "public/" src

2Fix

Drop 'public' from the path and start it with a slash.

/* before */
.hero { background: url(../public/hero.png); }
/* after: public/hero.png is served at /hero.png */
.hero { background: url(/hero.png); }

3Verify

Reload and confirm the request returns 200.

curl -I http://localhost:5173/hero.png

Confirmed by vite.dev

Did this fix it?

Cause 2 of 3

A relative path is written from the wrong folder

1Check

A relative url() in a stylesheet is handled like an import, so it must be correct relative to the CSS file itself, not to the page or to the file that imports the stylesheet.

ls src/assets
grep -n "url(" src/styles/main.css

2Fix

Write the path relative to the stylesheet. Vite then hashes the file and rewrites the URL for the build.

/* src/styles/main.css, image is src/assets/hero.png */
.hero { background: url(../assets/hero.png); }

3Verify

Run a production build and open the preview.

npm run build
npm run preview

Confirmed by vite.dev

Did this fix it?

Cause 3 of 3

The app is served from a subfolder but base is still /

1Check

Vite adjusts url() references during the build to follow the base option, whose default is /. If the site lives in a subfolder, every asset URL points at the host root.

grep -n "base" vite.config.*

2Fix

Set base to the folder the site is served from, or to ./ when the folder is not known in advance.

// vite.config.js
export default defineConfig({
  base: '/my-app/',
})

3Verify

Build and preview, then check the image URL starts with the base.

npm run build
npm run preview

Confirmed by vite.dev

Did this fix it?

How do I stop it coming back?

  • Put images used only by CSS next to the stylesheet or in src/assets, and reserve public for files that must keep their exact name.
  • Preview the production build before every deploy, not only the dev server.
  • Set base once in vite.config and use import.meta.env.BASE_URL in code that builds URLs by hand.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Web apps

tsconfig rejects allowImportingTsExtensions

An error that allowImportingTsExtensions needs noEmit or emitDeclarationOnly

allowImportingTsExtensions lets files import each other with .ts or .tsx extensions, and TypeScript only allows it together with noEmit or emitDeclarationOnly.

2 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.