Electron app shows 404 or a blank window once it is packaged
The packaged app opens a blank window, the dev build worksShort answer
In development Electron loads your React dev server over http. In a package it loads a file from disk, so a wrong file path, asset URLs that start with a slash, or a router that reads the URL path all break. Load the built index.html with loadFile, build with a relative base, and use a hash router.
Fix it fast
1Find out which cause you have
Open DevTools in the packaged app and read the Console and Network tabs. The failing URL tells you which cause below applies: a missing index.html, missing asset files, or a route that matched nothing.
grep -n "loadURL\|loadFile" main.js2Match what you see, then jump to its fix
- 1
The window stays blank and the Network tab shows index.html failing to loadThe main process loads the wrong file in productionFix - 2
The Network tab shows the JS and CSS files failing, and their paths begin with /assets/Asset URLs start with a slash, so they point at the disk rootFix - 3
The page loads, then your own Not Found route renders on first startThe router reads the URL path, and a local file has no app routesFix
- 1
What does the error look like?
The packaged app opens a blank window, the dev build worksYour own Not Found route renders when the packaged app starts
Cause 1 of 3
The main process loads the wrong file in production
1Check
BrowserWindow.loadFile takes a path to an HTML file relative to the root of your application, while loadURL takes a remote address or a file:// URL. Check which one runs in production, and that the path points at your build output.
grep -n "loadURL\|loadFile" main.js2Fix
Use loadURL for the dev server only, and loadFile with the build folder's index.html in production. Make sure the build folder is included in the packaged files.
const path = require('node:path');
// ELECTRON_START_URL is your own variable, e.g. http://localhost:5173 in development
if (process.env.ELECTRON_START_URL) {
win.loadURL(process.env.ELECTRON_START_URL);
} else {
win.loadFile(path.join(__dirname, 'dist', 'index.html'));
}3Verify
Package the app again and start it. The window now shows your first screen.
npm run build && npm run packageConfirmed by electronjs.org
Cause 2 of 3
Asset URLs start with a slash, so they point at the disk root
1Check
Open dist/index.html and read the script and link tags. A path like /assets/index.js is resolved from the root of the file system when the page is a local file.
grep -n "src=\|href=" dist/index.html2Fix
Build with a relative base so every generated URL is relative to the file that uses it.
// vite.config.js
export default defineConfig({
base: './',
});3Verify
Rebuild and check that index.html now references ./assets/ paths.
npm run build && grep -n "assets" dist/index.htmlConfirmed by vite.dev
Cause 3 of 3
The router reads the URL path, and a local file has no app routes
1Check
See which router your app creates. BrowserRouter matches the path part of the URL; a packaged app starts at a file path that none of your routes match.
grep -rn "BrowserRouter\|createBrowserRouter\|HashRouter" src/2Fix
Use a hash router. It stores the location in the hash part of the URL, which is not sent anywhere, so it does not depend on the file path.
import { HashRouter, Routes, Route } from "react-router";
<HashRouter>
<Routes>
<Route path="/" element={<Home />} />
</Routes>
</HashRouter>3Verify
Start the packaged app. The address in DevTools ends with #/ and your home route renders.
console.log(window.location.href)Confirmed by reactrouter.com
How do I stop it coming back?
- Test the packaged build on your own machine before every release, not only the dev server.
- Keep one config switch for dev and production loading in the main process.
- Decide the router type when you create an Electron project, not after the first package.
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- TaskvareA task and project-management suite: React on the web, Flutter on mobile, TypeScript underneath.
Related fixes
Web apps
Module not found for antd/dist/antd.less after upgrading to Ant Design 5
Module not found: Error: Can't resolve 'antd/dist/antd.less'
Ant Design 5 dropped Less and the bundled CSS file for CSS-in-JS, so antd/dist/antd.less no longer exists.
3 causes, each with a fixWeb apps
Astro Code component fails inside a React component
Astro components cannot be rendered directly via function call
Astro components such as Code only exist on the server and render static HTML.
2 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
How to catch and handle a 422 from Axios in a Redux thunk
action.error.message is 'Rejected' and action.payload is undefined
A 422 means the server read the request but cannot process its content, so repeating it unchanged fails again.
4 causes, each with a fixWeb apps
axios gets 429 Too Many Requests from a React app
429 (Too Many Requests)
A 429 comes from the server or an API gateway, not from axios: your client sent too many requests in a window.
4 causes, each with a fixWeb apps
Axios request is not cancelled when a React component unmounts
A cancelled request is logged as an error in the catch block
Axios cancels a request when you pass it an AbortSignal and later call abort() on its controller.
4 causes, each with a fix