{"record":{"id":"cfb8664cf115b6d4","repo":"vitejs/vite","slug":"client-id-conflict-detected-please-restart-the-de","errorCode":null,"errorMessage":"client ID conflict detected. Please restart the dev server.","messagePattern":"client ID conflict detected\\. Please restart the dev server\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/vite/src/node/server/bundledDev.ts","lineNumber":502,"sourceCode":"    if (truncated) debugHmr?.(`hmr update ${hmrOutput.changedIds.join(', ')}`)\n    this.environment.logger.info(\n      colors.green(`hmr update `) + colors.dim(formatted),\n      {\n        clear: true,\n        timestamp: true,\n      },\n    )\n  }\n}\n\nclass Clients {\n  private clientToId = new Map<NormalizedHotChannelClient, string>()\n  private idToClient = new Map<string, NormalizedHotChannelClient>()\n\n  setupIfNeeded(client: NormalizedHotChannelClient, clientId: string) {\n    const id = this.clientToId.get(client)\n    if (id && id !== clientId) {\n      throw new Error(\n        'client ID conflict detected. Please restart the dev server.',\n      )\n    }\n    this.clientToId.set(client, clientId)\n    this.idToClient.set(clientId, client)\n  }\n\n  get(id: string): NormalizedHotChannelClient | undefined {\n    return this.idToClient.get(id)\n  }\n\n  getId(client: NormalizedHotChannelClient): string | undefined {\n    return this.clientToId.get(client)\n  }\n\n  getAll(): NormalizedHotChannelClient[] {\n    return Array.from(this.idToClient.values())\n  }","sourceCodeStart":484,"sourceCodeEnd":520,"githubUrl":"https://github.com/vitejs/vite/blob/b4d66fee14d970f45b8a6f3d7d6aee73ca9b88ab/packages/vite/src/node/server/bundledDev.ts#L484-L520","documentation":"Clients.setupIfNeeded maps a hot channel client to its clientId. If the same client object is already registered with a different id, Vite throws because the client identity and the id are out of sync — usually a symptom of a stale/HMR-desynced connection. The message asks the user to restart the dev server.","triggerScenarios":"A hot channel client reconnects (vite:client-connected / vite:client:connect) and presents a clientId that differs from the one previously bound to the same underlying transport client. Happens when HMR state diverges from the server's client map.","commonSituations":"Long-lived dev sessions with aggressive HMR, custom transports/proxies that reuse connection objects, or bugs in the HMR client that regenerate ids without dropping the old mapping.","solutions":["Restart the dev server as the message suggests.","Hard-reload the browser tab to drop stale HMR client state.","If using a custom transport, ensure each new clientId is paired with a new client object (or call delete on the old mapping).","Update Vite — this is often a transient HMR desync fixed in newer patches."],"exampleFix":"// before — custom transport reuses client object with new id\nclient.emit('vite:client-connected', { clientId: newId })\n// after — drop the old mapping first\nclients.delete(oldClient)\nclient.emit('vite:client-connected', { clientId: newId })","handlingStrategy":"validation","validationCode":"// For custom transports, ensure clientId mapping is unique\nfunction assertNoClientIdConflict(clients, client, clientId) {\n  const existing = clients.getId(client)\n  if (existing && existing !== clientId) throw new Error('client ID conflict; restart dev server')\n}","typeGuard":null,"tryCatchPattern":"try {\n  clients.setupIfNeeded(client, clientId)\n} catch (e) {\n  if (/client ID conflict/.test(e.message)) { await server.restart() }\n  throw e\n}","preventionTips":["Pair each new clientId with a fresh client object or delete the old mapping.","Restart the dev server when HMR behaves erratically.","Hard-reload the browser tab to reset HMR client state."],"tags":["hmr","bundled-dev","dev-server","transport"],"backgroundTag":null,"analyzedSha":"b4d66fee14d970f45b8a6f3d7d6aee73ca9b88ab","analyzedAt":"2026-08-11T11:49:19.515Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}