Laravel with Vite logs "WebSocket connection to ... failed" in the browser console
WebSocket connection to ... failedShort answer
Laravel learns where the Vite dev server lives from the public/hot file, and the Vite client opens its WebSocket at that address. It fails when the address is not reachable from the browser, when an HTTPS site meets a plain HTTP dev server, when the dev certificate is untrusted, or when the port moved. Read public/hot first.
Fix it fast
1Find out which cause you have
Read the hot file. It holds the address Laravel gives to the browser for every Vite asset. Compare it with the address you open the site on and with the Local line that npm run dev prints.
cat public/hot # PowerShell: Get-Content public/hot2Match what you see, then jump to its fix
- 1
public/hot holds something like http://[::1]:5173 or http://0.0.0.0:5173, while the site opens under a name such as my-app.testThe address in public/hot is not one the browser can reachFix - 2
The site opens at https://my-app.test, while public/hot starts with http://An HTTPS site talks to a plain HTTP dev serverFix - 3
public/hot already starts with https://, yet the WebSocket and the assets still failThe browser does not trust the dev server certificateFix - 4
The port in the failing URL differs from the port on the Local line printed nowThe dev server moved to another port behind an open pageFix
- 1
What does the error look like?
WebSocket connection to ... failed[vite] failed to connect to websocket.Check out your Vite / network configuration and https://vite.dev/config/server-options.html#server-hmr .
Cause 1 of 4
The address in public/hot is not one the browser can reach
1Check
With no host set, the Laravel plugin writes the address the dev server bound to, and wraps an IPv6 address in square brackets. An explicit hmr.host wins over everything, then an explicit server.host. The browser must be able to open exactly the address written there, and the dev server must listen on it.
cat public/hot
curl -I "$(cat public/hot)/@vite/client"2Fix
Give Vite the host name your site already uses, in both server.host and hmr.host, so the file and the WebSocket point at a name that resolves on your machine.
// vite.config.js
import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
const host = 'my-app.test';
export default defineConfig({
plugins: [
laravel({ input: ['resources/css/app.css', 'resources/js/app.js'], refresh: true }),
],
server: {
host,
hmr: { host },
},
});3Verify
Restart the dev server. The hot file must show the new host, and the console must stay free of WebSocket errors after a hard reload.
npm run dev
cat public/hotConfirmed by raw.githubusercontent.com
Cause 2 of 4
An HTTPS site talks to a plain HTTP dev server
1Check
The Laravel docs warn that a site served over HTTPS can run into trouble connecting to the Vite dev server. The plugin writes https in the hot file only when the Vite server itself has TLS configured, and it detects certificates by itself only for Herd and Valet, or from the VITE_DEV_SERVER_KEY and VITE_DEV_SERVER_CERT variables.
cat public/hot
grep -n "https\|detectTls" vite.config.js2Fix
With Herd or Valet, set detectTls to the host of the secured site if it differs from the folder name. With any other web server, create a trusted certificate for the site name and hand it to Vite, with the same host on the WebSocket.
// vite.config.js
import fs from 'fs';
const host = 'my-app.test';
export default defineConfig({
// plugins ...
server: {
host,
hmr: { host },
https: {
key: fs.readFileSync(`/path/to/${host}.key`),
cert: fs.readFileSync(`/path/to/${host}.crt`),
},
},
});3Verify
Restart the dev server. public/hot must now start with https://my-app.test, and the page must load without a console error.
npm run dev
cat public/hotConfirmed by laravel.com
Cause 3 of 4
The browser does not trust the dev server certificate
1Check
This happens with a self-signed certificate, for example one made by the basic-ssl plugin. The page may load, but the browser refuses the dev server on its own origin until you accept its certificate.
npm run dev2Fix
Open the Local link that npm run dev prints, in the same browser, and accept the certificate warning once. For a permanent fix, use a trusted certificate as in the cause above.
# 1. npm run dev
# 2. open the "Local" URL from its output in the browser and accept the warning
# 3. reload the Laravel page3Verify
Reload the Laravel page; the WebSocket error must be gone.
cat public/hotConfirmed by laravel.com
Cause 4 of 4
The dev server moved to another port behind an open page
1Check
When the port is taken, Vite tries the next free one. The plugin rewrites public/hot when the server starts, but a page that was rendered earlier still carries the old address, because Laravel reads the file while it renders each response.
cat public/hot
# compare with the Local line in the npm run dev output2Fix
Stop whatever still holds port 5173 (often an older dev server), and make Vite exit instead of drifting to another port. Then reload the page.
// vite.config.js
export default defineConfig({
// plugins ...
server: {
port: 5173,
strictPort: true,
},
});3Verify
Start the dev server. It must report port 5173, or stop with an error that tells you the port is busy.
npm run devConfirmed by vite.dev
How do I stop it coming back?
- Use the same host name for the site, server.host and hmr.host, and write it down in vite.config.js once.
- Run one dev server per project and stop it with Ctrl+C, so the hot file and the port stay in step.
- Secure the site and Vite together: when the site is HTTPS, give the dev server a certificate on the same host.
- Treat public/hot as the first thing to read whenever a Vite asset or WebSocket request fails.
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.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
- Spotless LaundryAn on-demand laundry app: Flutter on a Laravel back end, with Firebase for live updates.
Related fixes
Web apps
Vite hot reload fails with a WebSocket connection error behind a proxy or HTTPS
HMR does not work behind a reverse proxy
Vite's hot module reload talks to the dev server over a WebSocket.
4 causes, each with a fixBack end
Laravel says Vite manifest not found at public/build/manifest.json
Vite manifest not found at: /var/www/app/public/build/manifest.json
Laravel's @vite directive looks for a running dev server first, then for a built manifest file.
3 causes, each with a fixBack end
Laravel mix() fails with 'The Mix manifest does not exist'
The Mix manifest does not exist.
The mix() helper reads mix-manifest.json to find the hashed asset name, and that file only appears after Mix has compiled your assets.
2 causes, each with a fixBack end
Laravel mix() throws Unable to locate Mix file
Unable to locate Mix file: /css/app.css.
This error means mix-manifest.json exists but has no entry for the path you passed to mix().
4 causes, each with a fixBack end
npm run production fails in Laravel Mix with an unknown --hide-modules option
Unknown argument: --hide-modules
The scripts in your package.json were written for Mix 5, which called webpack directly with flags such as --hide-modules.
3 causes, each with a fixBack end
Laravel npm run dev says the mix command was not found
Command "mix" not found when running npm run dev
The mix program comes from the laravel-mix package.
3 causes, each with a fix