A background image in CSS does not load in Vite
404 (Not Found) for an image or font requested through url() in CSSShort 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.
Fix it fast
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=*.scss2Match what you see, then jump to its fix
- 1
The failed request URL contains the folder name public, or the CSS path contains public/The path points into public with the wrong formFix - 2
The 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
Images load in dev and 404 after deploy to https://host/my-app/The app is served from a subfolder but base is still /Fix
- 1
What does the error look like?
404 (Not Found) for an image or font requested through url() in CSSBackground 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/" src2Fix
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.pngConfirmed by vite.dev
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.css2Fix
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 previewConfirmed by vite.dev
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 previewConfirmed by vite.dev
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 fixWeb apps
Apollo Server rejects a request as a potential CSRF
HTTP 400 Bad Request from the GraphQL endpoint
Apollo Server's CSRF prevention is on by default.
3 causes, each with a fixWeb apps
React shows Attempted import error when importing a component or function
Attempted import error:
The build found the file but not the name you asked for.
2 causes, each with a fixWeb apps
AxiosError Network Error with code ERR_NETWORK in a React app
Network Error
ERR_NETWORK means the request produced no readable response.
4 causes, each with a fixWeb apps
Axios get works with a URL string but ignores the object passed as the second argument
The server log shows a GET with no query string
axios.get takes a URL and an optional config object.
3 causes, each with a fixWeb apps
Can't resolve '../axios' in a React project
Module not found: Error: Can't resolve '../axios'
A path that starts with ./ or ../ is a file path, not the axios package.
3 causes, each with a fix