Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Laravel with Vite logs "WebSocket connection to ... failed" in the browser console

ErrorWebSocket connection to ... failed

Short 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.

  • Applies to Laravel 12, laravel-vite-plugin 1.x, Vite 7, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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/hot
  2. 2Match what you see, then jump to its fix

    1. 1public/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. 2The site opens at https://my-app.test, while public/hot starts with http://An HTTPS site talks to a plain HTTP dev serverFix
    3. 3public/hot already starts with https://, yet the WebSocket and the assets still failThe browser does not trust the dev server certificateFix
    4. 4The 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

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/hot

Confirmed by raw.githubusercontent.com

Did this fix it?

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.js

2Fix

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/hot

Confirmed by laravel.com

Did this fix it?

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 dev

2Fix

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 page

3Verify

Reload the Laravel page; the WebSocket error must be gone.

cat public/hot

Confirmed by laravel.com

Did this fix it?

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 output

2Fix

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 dev

Confirmed by vite.dev

Did this fix it?

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:

Related fixes

Next step

Want this handled for good?

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