Diagnosing Quasar Dev Server Startup and HMR Failures

Recognizable condition

You run `quasar dev` in a Quasar Framework project and one of the following happens:

• The command exits immediately with a port-in-use error such as `EADDRINUSE`.
• The CLI starts but never prints the HMR-connected message and the browser tab never opens.
• You save a Vue single-file component, but the browser shows the old markup until you refresh manually.

These symptoms mean the development server failed to bind its port, failed to complete the Vite hot-module-replacement (HMR) handshake, or both. HMR is the mechanism that pushes saved source changes to the running browser page without a full reload. The useful takeaway is that most local failures trace to three causes: a process already holding the configured port, a stale `node_modules/.cache` or `.quasar` directory after a CLI upgrade, or mismatched Vue/Vite peer dependencies from an interrupted `npm install`.

Cause and diagnostic table

Condition	Likely cause	First check
`quasar dev` exits with port-in-use	Another process is listening on `devServer.port`	List listeners on the configured port
Startup hangs; no browser opens	Stale cache or blocked localhost assets	Compare cache timestamps with dependency versions
Edits save but browser does not update	HMR socket failed; proxy or port mismatch	Check browser DevTools for WebSocket or 404 errors
Crash during dependency resolution	Missing peer dependencies or incompatible Vue/Vite versions	Run `quasar info` and inspect `package.json`

Ordered checks

1. Confirm the project and CLI version. Run `quasar info` in the project root. This command requires no elevated permissions. Record the Quasar CLI version, Quasar package version, Node version, and whether the app uses Vite or Webpack mode. Fixes below assume Quasar CLI v2 with Vite; behavior differs in Webpack mode.
2. Start the server and capture the exit code. Run `quasar dev` in the project root. No special permissions are required. If the command exits, note the exit code and the port mentioned in the error. If it hangs, wait until the terminal output stops changing, then press Ctrl+C.
3. List listeners on the configured port. On macOS or Linux, run `lsof -i :` in a terminal, replacing `` with the port from `quasar.config.js` (default is often 8080). On Windows, run `netstat -ano | findstr :` in Command Prompt. These are read-only commands. Expected result: either no output, meaning the port is free, or a process name and PID, meaning something else owns the port.
4. Inspect cache and artifact directories. Compare the modification times of `node_modules/.cache`, `.quasar`, and `dist` against the last change to `package.json`. If the cache is newer than your dependency changes or older than a CLI upgrade, it may be stale.
5. Check browser network behavior. If the server starts but edits do not appear, open the browser DevTools Network tab, reload once, then edit and save a component template. Look for `localhost:` asset requests returning 200 and a WebSocket connection to the Vite HMR endpoint. Blocked requests or 404/403 responses indicate a proxy or port mismatch.

Fixes tied to findings

1. Port conflict: stop the other process or change the port

If `lsof` or `netstat` shows another process on the port, stop that process or change Quasar's port. Edit `quasar.config.js` in the project root:

module.exports = function (ctx) {
  return {
    devServer: {
      port: 8081,
      open: true
    },
    // framework, build, and other properties unchanged
  }
}

If you change the port, update any hardcoded `localhost:8080` references in boot files or API proxy configuration so CORS and proxy assumptions still match the new port. Changing `devServer.port` may break proxy assumptions; verify related `baseUrl` values after editing.

2. Stale cache: clear cache and artifacts, then reinstall

If timestamps suggest a stale cache after a CLI upgrade, delete the local cache and build artifacts. Run these commands in the project root with normal user write permissions:

rm -rf node_modules/.cache .quasar dist
npm install

Deleting `dist` removes build artifacts; confirm your source-control status is clean before deletion so you do not lose uncommitted generated output. There is no rollback for deleted cache directories; `npm install` is the recovery step. After reinstalling, run `quasar dev` again.

Do not edit files inside `node_modules`; changes are lost on reinstall and can mask dependency mismatches.

3. Dependency mismatch: align peer dependencies

If `quasar info` shows Vue or Vite versions that do not match the Quasar major version you are using, remove `node_modules` and the lockfile, then reinstall:

rm -rf node_modules package-lock.json
npm install

This requires network access and may update the lockfile. Review the diff before committing.

Escalation criteria

Escalate to the project maintainers with a minimal reproduction if all of the following are true:

• A clean reinstall on Node LTS still fails.
• The port is free, the cache is cleared, and dependency versions match the Quasar major version.
• Browser DevTools still show blocked HMR WebSocket connections or asset requests.

Include `quasar info` output, your operating system and Node versions, the `quasar.config.js` devServer block, and a minimal repository or steps to reproduce.

Verification

Run `quasar dev` and confirm the CLI reports the configured port and an HMR-connected status in the terminal. Edit a Vue component template, save it, and confirm the browser reflects the change without a manual page reload. Run `quasar info` again to verify Node, Quasar CLI, and Quasar package versions match the versions assumed in the fix. Check the browser DevTools Network tab for `localhost:` asset requests returning 200 instead of blocked or proxy errors.

Limitation: This guide covers local development server startup and HMR. It does not cover production builds (`quasar build`) or deployment-specific proxy configuration. Behavior varies between Quasar CLI versions and Vite/Webpack modes; confirm the installed major version before applying version-specific fixes. Verify these steps against your installed Quasar CLI major version before applying them in a shared environment.