{"record":{"id":"b4991f052bb9f5c6","repo":"decolua/9router","slug":"failed-to-start-proxy","errorCode":null,"errorMessage":"Failed to start proxy","messagePattern":"Failed to start proxy","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/app/(dashboard)/dashboard/token-saver/TokenSaverClient.js","lineNumber":191,"sourceCode":"        loading: false,\n      });\n      setHeadroomExtras({\n        version: null,\n        extras: { code: false, ml: false },\n        available: [\"code\", \"ml\"],\n        loading: false,\n      });\n      setPendingExtras([]);\n    }\n  }, []);\n\n  const handleHeadroomStart = useCallback(async () => {\n    setHeadroomActionError(\"\");\n    setHeadroomActionLoading(true);\n    try {\n      const res = await fetch(\"/api/headroom/start\", { method: \"POST\" });\n      const data = await res.json().catch(() => ({}));\n      if (!res.ok) throw new Error(data.error || \"Failed to start proxy\");\n      await refreshHeadroomStatus();\n    } catch (e) {\n      setHeadroomActionError(e.message);\n    } finally {\n      setHeadroomActionLoading(false);\n    }\n  }, [refreshHeadroomStatus]);\n\n  const handleHeadroomStop = useCallback(async () => {\n    setHeadroomActionLoading(true);\n    try {\n      await fetch(\"/api/headroom/stop\", { method: \"POST\" });\n      await refreshHeadroomStatus();\n    } finally {\n      setHeadroomActionLoading(false);\n    }\n  }, [refreshHeadroomStatus]);\n","sourceCodeStart":173,"sourceCodeEnd":209,"githubUrl":"https://github.com/decolua/9router/blob/90b52e06ffd666b7929554211474d01588f6b1f8/src/app/(dashboard)/dashboard/token-saver/TokenSaverClient.js#L173-L209","documentation":"handleHeadroomStart throws this when POST /api/headroom/start responds non-2xx and its body has no `error` field. It signals the token-saver proxy failed to start; the message is stored in headroomActionError and displayed in the UI.","triggerScenarios":"POST /api/headroom/start returns non-2xx: proxy binary/executable missing or not installed, port already in use, permission error spawning the process, or the server returns a bare status without a JSON error body (data.error undefined due to res.json() catch → {}).","commonSituations":"Another process already bound to the headroom proxy port; extras not installed before pressing start; executable lacks permission (chmod) or platform binary missing; server environment lacking required runtime.","solutions":["Read the server's actual error body/status for /api/headroom/start in the network tab","Check whether the headroom proxy port is already in use (lsof/netstat) and free it","Install the headroom extras first if status shows available but not installed","Check server logs for spawn/permission errors on the proxy executable"],"exampleFix":"// before\nif (!res.ok) throw new Error(data.error || \"Failed to start proxy\");\n// after\nif (!res.ok) throw new Error(data.error || `Failed to start proxy (HTTP ${res.status})`);","handlingStrategy":"try-catch","validationCode":"// check extras installed before attempting start\nif (!headroomExtras.extras?.code && !headroomExtras.extras?.ml) {\n  setHeadroomActionError(\"Install headroom extras first\");\n  return;\n}","typeGuard":null,"tryCatchPattern":"try {\n  const res = await fetch(\"/api/headroom/start\", { method: \"POST\" });\n  const data = await res.json().catch(() => ({}));\n  if (!res.ok) throw new Error(data.error || `Failed to start proxy (HTTP ${res.status})`);\n  await refreshHeadroomStatus();\n} catch (e) {\n  setHeadroomActionError(e.message);\n}","preventionTips":["Free the headroom proxy port before starting (check for stale processes)","Install required extras before pressing start","Check server logs for spawn/permission errors on the proxy executable","Retry start once after a failure; repeated failures need server-side diagnosis"],"tags":["http","proxy","process-management","dashboard"],"backgroundTag":"http-request-failed","analyzedSha":"90b52e06ffd666b7929554211474d01588f6b1f8","analyzedAt":"2026-08-30T21:05:45.952Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}