{"record":{"id":"e6947f4b586b9e03","repo":"thedotmack/claude-mem","slug":"claude-mem-host-observer-port-configured-has-no","errorCode":null,"errorMessage":"CLAUDE_MEM_HOST_OBSERVER_PORT=${configured} has nothing listening. Start your OpenAI-compatible observer on that port, then rerun with --provider host.","messagePattern":"CLAUDE_MEM_HOST_OBSERVER_PORT=(.+?) has nothing listening\\. Start your OpenAI-compatible observer on that port, then rerun with --provider host\\.","errorType":"exception","errorClass":"HostObserverUnavailableError","httpStatus":null,"severity":"error","filePath":"src/npx-cli/cmem-memory-credentials.ts","lineNumber":253,"sourceCode":"    const configured = parsePort(configuredRaw);\n    if (configured == null) {\n      throw new HostObserverUnavailableError(\n        `CLAUDE_MEM_HOST_OBSERVER_PORT=${configuredRaw} is not a valid port. Set it to the port your OpenAI-compatible observer already listens on.`,\n      );\n    }\n    if (worker != null && configured === worker) {\n      throw new HostObserverUnavailableError(\n        `CLAUDE_MEM_HOST_OBSERVER_PORT=${configured} is the claude-mem worker port. Point it at your OpenAI-compatible observer instead.`,\n      );\n    }\n    const status = probe(configured);\n    if (status === 'observer') return String(configured);\n    if (status === 'occupied') {\n      throw new HostObserverUnavailableError(\n        `CLAUDE_MEM_HOST_OBSERVER_PORT=${configured} is occupied by a process that is not an OpenAI-compatible observer. Stop that process or point CLAUDE_MEM_HOST_OBSERVER_PORT at your observer.`,\n      );\n    }\n    throw new HostObserverUnavailableError(\n      `CLAUDE_MEM_HOST_OBSERVER_PORT=${configured} has nothing listening. Start your OpenAI-compatible observer on that port, then rerun with --provider host.`,\n    );\n  }\n\n  const candidates = hostObserverCandidatePorts(workerPort, env);\n  for (const port of candidates) {\n    const status = probe(port);\n    if (status === 'observer') return String(port);\n  }\n\n  throw new HostObserverUnavailableError(\n    `No OpenAI-compatible host observer is listening on 127.0.0.1:${candidates.join(' or ') || HOST_OBSERVER_DEFAULT_PORT}. Host mode uses an observer you already run; claude-mem does not start one. Start your observer, then rerun with --provider host. If it uses another port, set CLAUDE_MEM_HOST_OBSERVER_PORT.`,\n  );\n}\n\nexport function buildHostObserverSettings(\n  observerModel: 'cursor' | 'grok-bot',\n  settings: SettingsLike,","sourceCodeStart":235,"sourceCodeEnd":271,"githubUrl":"https://github.com/thedotmack/claude-mem/blob/8bc631a71a487424b866756e43a6efa4574cc66b/src/npx-cli/cmem-memory-credentials.ts#L235-L271","documentation":"If CLAUDE_MEM_HOST_OBSERVER_PORT is set and explicitly given, claude-mem never falls back to default candidate ports: whatever the probe reports other than 'observer' throws. 'free' (nothing listening, bind test succeeds) produces this error telling you to actually start the observer.","triggerScenarios":"resolveHostObserverPort with CLAUDE_MEM_HOST_OBSERVER_PORT set to a valid port on which no process is listening (probe returns 'free'), while running install with --provider host.","commonSituations":"Observer crashed or was never started; firewall/container isolation makes loopback unreachable; wrong port typo'd to an unused number; observer only bound to a non-loopback interface.","solutions":["Start your OpenAI-compatible observer so it listens on the configured port, then rerun the install with --provider host","Verify it is up: curl http://127.0.0.1:$CLAUDE_MEM_HOST_OBSERVER_PORT/v1/models","If the observer runs on a different port, update CLAUDE_MEM_HOST_OBSERVER_PORT to match","Unset CLAUDE_MEM_HOST_OBSERVER_PORT to fall back to auto-probing 37777/37778"],"exampleFix":"// before\nexport CLAUDE_MEM_HOST_OBSERVER_PORT=4141  # nothing listening\nnpx claude-mem install --provider host\n// after\nstart-my-observer --port 4141\nexport CLAUDE_MEM_HOST_OBSERVER_PORT=4141\nnpx claude-mem install --provider host","handlingStrategy":"validation","validationCode":"const port = process.env.CLAUDE_MEM_HOST_OBSERVER_PORT;\nif (port) {\n  const up = await fetch(`http://127.0.0.1:${port}/v1/models`).then(r => r.ok).catch(() => false);\n  if (!up) throw new Error(`Observer not listening on ${port}; start it before installing`);\n}","typeGuard":null,"tryCatchPattern":"try {\n  const port = resolveHostObserverPort(workerPort, env);\n} catch (e) {\n  if (e instanceof HostObserverUnavailableError && e.message.includes('has nothing listening')) {\n    // start the observer, then retry the install\n  } else throw e;\n}","preventionTips":["Start the observer process before running install --provider host","Health-check the observer with curl /v1/models as a pre-install step in scripts","Ensure the observer binds to 127.0.0.1 and is not blocked by container/firewall isolation"],"tags":["network","host-observer","connection","env-var"],"backgroundTag":"connection-refused","analyzedSha":"8bc631a71a487424b866756e43a6efa4574cc66b","analyzedAt":"2026-09-09T10:47:06.009Z","contentChangedAt":"2026-09-09T10:47:06.009Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}