Maaz Zindani

Loading the index…

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

Laravel Sail page cannot load assets from the Vite dev server on port 5173

ErrorThe page loads without its CSS and JavaScript while the app itself answers

Short answer

In Sail the Vite dev server runs inside the container and the browser reaches it through a published port. Assets fail when npm run dev is not running in the container, when compose.yaml does not publish the Vite port or it differs from VITE_PORT, when public/hot holds the wrong host, or when a stale hot file outlives the server.

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

Fix it fast

  1. 1Find out which cause you have

    Read the hot file inside the container, then ask the dev server from your own machine whether it answers on the published port. A refused connection points at the first or second cause; a wrong address in the file points at the third or fourth.

    sail shell
    cat public/hot
    exit
    curl -I http://localhost:5173/@vite/client
  2. 2Match what you see, then jump to its fix

    1. 1public/hot is missing, or it exists and nothing answers on port 5173The dev server is not running inside the containerFix
    2. 2The dev server prints its Local line, yet the browser cannot connect to localhost:5173The Vite port is not published, or differs from VITE_PORTFix
    3. 3public/hot shows an address other than http://localhost:5173, for example http://0.0.0.0:5173public/hot holds a host the browser does not useFix
    4. 4public/hot exists, no dev server is running, and the page still asks for dev server URLsA stale hot file outlived the dev serverFix

What does the error look like?

  • The page loads without its CSS and JavaScript while the app itself answers
  • Requests for /@vite/client and your entry files fail in the browser network tab

Cause 1 of 4

The dev server is not running inside the container

1Check

Sail runs the app in a container, so Node and npm commands go through Sail as well. The Laravel plugin applies its Sail host and port rules only when the LARAVEL_SAIL variable is set, and Sail sets it inside the container. The process also has to stay running in its own terminal.

sail shell
ls -l public/hot

2Fix

Install the packages and start the dev server through Sail, and leave that terminal open while you work.

sail npm install
sail npm run dev

3Verify

The terminal prints a Local line for port 5173, and public/hot now holds http://localhost:5173.

sail shell
cat public/hot

Confirmed by laravel.com

Did this fix it?

Cause 2 of 4

The Vite port is not published, or differs from VITE_PORT

1Check

Sail publishes the Vite port in compose.yaml through VITE_PORT, default 5173. Under Sail the Laravel plugin starts Vite on that same port, unless server.port is set in vite.config.js, and it exits instead of moving to another port. A compose.yaml without the ports line, or a server.port that differs from the published one, leaves the browser with nothing to connect to.

grep -n "VITE_PORT" compose.yaml .env
grep -n "port" vite.config.js

2Fix

Make sure the service has the ports line below, remove server.port from vite.config.js, and set VITE_PORT in .env only if you want a different port. Then recreate the containers.

# compose.yaml, service laravel.test
ports:
  - '${APP_PORT:-80}:80'
  - '${VITE_PORT:-5173}:${VITE_PORT:-5173}'

# .env (only for a different port)
VITE_PORT=5174

# then
sail up -d

3Verify

With the dev server running, the published port answers from your own machine.

curl -I http://localhost:5173/@vite/client

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 3 of 4

public/hot holds a host the browser does not use

1Check

Under Sail the plugin binds Vite to 0.0.0.0 and writes localhost into the hot file. If you set server.host yourself, that value is written as it is, and 0.0.0.0 is a bind address, not an address to browse. On WSL2 the Laravel docs also ask for hmr.host to be localhost.

grep -n "host" vite.config.js
sail shell
cat public/hot

2Fix

Remove the explicit server.host, or add hmr.host set to localhost, which the plugin prefers when it writes the hot file.

// vite.config.js
export default defineConfig({
  // plugins ...
  server: {
    hmr: {
      host: 'localhost',
    },
  },
});

3Verify

Restart sail npm run dev. The hot file must show http://localhost:5173.

sail shell
cat public/hot

Confirmed by laravel.com

Did this fix it?

Cause 4 of 4

A stale hot file outlived the dev server

1Check

The @vite directive treats the existence of public/hot as "the dev server is running" and loads every asset from the address inside it. The plugin deletes the file when the process exits normally or receives SIGINT, SIGTERM or SIGHUP, and nothing else deletes it. A process that dies another way can leave it behind.

sail shell
ls -l public/hot

2Fix

Delete the file, or start the dev server again, which rewrites it. For a build without a dev server, remove the file and build the assets, then @vite loads the built files.

sail shell
rm public/hot
exit
sail npm run build

3Verify

Reload the page. Assets now load from the build folder, or from the fresh dev server.

curl -I http://localhost

Confirmed by raw.githubusercontent.com

Did this fix it?

How do I stop it coming back?

  • Start the dev server only through sail npm run dev, and stop it with Ctrl+C so that the hot file is removed.
  • Keep VITE_PORT in .env as the one place that decides the port, and leave server.port out of vite.config.js.
  • After you edit the ports in compose.yaml, run sail up -d so that Docker Compose recreates the container.
  • Do not set server.host under Sail unless you also set hmr.host.

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

Back end

The AWS SDK in Node.js cannot find any credentials

Missing credentials in config, if using AWS_CONFIG_FILE, set AWS_SDK_LOAD_CONFIG=1

The AWS SDK walks a fixed credential chain: code, environment variables, the shared files in ~/.aws, then role sources such as ECS or EC2.

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