{"record":{"id":"f2653a58a59f29e6","repo":"paperclipai/paperclip","slug":"paperclip-vite-hmr-protocol-must-be-ws-or-wss","errorCode":null,"errorMessage":"PAPERCLIP_VITE_HMR_PROTOCOL must be ws or wss","messagePattern":"PAPERCLIP_VITE_HMR_PROTOCOL must be ws or wss","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/src/app.ts","lineNumber":166,"sourceCode":"\nexport function isDatabaseConnectionUnavailableError(err: unknown): boolean {\n  const error = err as { code?: unknown; message?: unknown; cause?: unknown };\n  if (error?.code === \"ECONNREFUSED\") return true;\n  return Boolean(error?.cause && isDatabaseConnectionUnavailableError(error.cause));\n}\n\nexport function resolveViteHmrPort(serverPort: number): number {\n  return derivePaperclipViteHmrPort(serverPort);\n}\n\nexport function resolveViteHmrHost(bindHost: string): string | undefined {\n  const normalized = bindHost.trim().toLowerCase();\n  if (\n    normalized === \"0.0.0.0\"\n    || normalized === \"::\"\n    || normalized === \"127.0.0.1\"\n    || normalized === \"::1\"\n    || normalized === \"localhost\"\n  ) return undefined;\n  return bindHost;\n}\n\nexport function resolveViteHmrProtocol(value: string | undefined): \"ws\" | \"wss\" | undefined {\n  if (!value) return undefined;\n  if (value === \"ws\" || value === \"wss\") return value;\n  throw new Error(\"PAPERCLIP_VITE_HMR_PROTOCOL must be ws or wss\");\n}\n\nexport function listenViteHmrServer(server: HttpServer, port: number, bindHost: string): Promise<void> {\n  return new Promise((resolve, reject) => {\n    const onError = (error: Error) => {\n      server.off(\"listening\", onListening);\n      reject(error);\n    };\n    const onListening = () => {\n      server.off(\"error\", onError);","sourceCodeStart":148,"sourceCodeEnd":184,"githubUrl":"https://github.com/paperclipai/paperclip/blob/01ad8584922b5d85292b1723cae71fa0d9b07a19/server/src/app.ts#L148-L184","documentation":"Environment-variable validation in resolveViteHmrProtocol: PAPERCLIP_VITE_HMR_PROTOCOL is set but is neither 'ws' nor 'wss' (case-sensitive after trim/lowercase handling upstream). The value is passed straight into Vite's HMR config which only accepts those two protocols, so dev-server startup aborts with this guard.","triggerScenarios":"Thrown at server/src/app.ts:162 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Set PAPERCLIP_VITE_HMR_PROTOCOL to ws or wss.","Unset PAPERCLIP_VITE_HMR_PROTOCOL to use the default."],"exampleFix":null,"handlingStrategy":"validation","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"01ad8584922b5d85292b1723cae71fa0d9b07a19","analyzedAt":"2026-08-18T22:49:45.177Z","contentChangedAt":"2026-08-18T22:49:45.177Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}