vitejs/vite · error · Error

client ID conflict detected. Please restart the dev server.

Error message

client ID conflict detected. Please restart the dev server.

What it means

Clients.setupIfNeeded at packages/vite/src/node/server/bundledDev.ts:510 tracks hot-channel clients by an id reported in the vite:client-connected payload. If the same channel client object reconnects with a different clientId than the one it first registered, the dev server's bundled-dev state is inconsistent and it asks the user to restart.

Source

Thrown at packages/vite/src/node/server/bundledDev.ts:510

    if (truncated) debugHmr?.(`hmr update ${hmrOutput.changedIds.join(', ')}`)
    this.environment.logger.info(
      colors.green(`hmr update `) + colors.dim(formatted),
      {
        clear: true,
        timestamp: true,
      },
    )
  }
}

class Clients {
  private clientToId = new Map<NormalizedHotChannelClient, string>()
  private idToClient = new Map<string, NormalizedHotChannelClient>()

  setupIfNeeded(client: NormalizedHotChannelClient, clientId: string) {
    const id = this.clientToId.get(client)
    if (id && id !== clientId) {
      throw new Error(
        'client ID conflict detected. Please restart the dev server.',
      )
    }
    this.clientToId.set(client, clientId)
    this.idToClient.set(clientId, client)
  }

  get(id: string): NormalizedHotChannelClient | undefined {
    return this.idToClient.get(id)
  }

  getId(client: NormalizedHotChannelClient): string | undefined {
    return this.clientToId.get(client)
  }

  getAll(): NormalizedHotChannelClient[] {
    return Array.from(this.idToClient.values())
  }

View on GitHub (pinned to 89620f09af)

Solutions

1. Restart the dev server as the message instructs to reset the client-id map.
2. If you author a custom hot channel, ensure a given client object always reports the same clientId.
3. Update Vite / the HMR client to a version that stabilizes clientId across reconnects.
4. Reduce reconnect churn (fix the proxy/network instability causing repeated HMR disconnects).

Example fix

// before: custom transport rotates id on reconnect
client = { send, on: cb => cb({ clientId: crypto.randomUUID() }) }

// after: keep a stable id per client object
const id = crypto.randomUUID()
client = { send, on: cb => cb({ clientId: id }) }

When it happens

Trigger: A hot channel reusing a client object across reconnects but generating a new clientId each time (e.g. HMR websocket re-handshaking with a fresh id); multiple browser tabs sharing a channel; a custom transport that does not preserve clientId identity for a given connection.

Common situations: Long-running dev sessions where the HMR socket reconnects after sleep/ network blip and the client id rotates; misbehaving custom transport / SSR hot channel; aggressive tab refresh loops.

Related errors

• currently full bundle mode is only available for client envi
• multiple output options are not supported in dev mode
• fetchModule is disabled in this environment
• invalid hot.accept() usage.
• HMR is not supported by this runner transport, but `hmr` opt

AI-assisted analysis of vitejs/vite@89620f09af (2026-08-03). Data as JSON: /data/errors/cfb8664cf115b6d4.json. Report an issue: GitHub.