thedotmack/claude-mem · error · HostObserverUnavailableError

No OpenAI-compatible host observer is listening on 127.0.0.1

Error message

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.

What it means

When CLAUDE_MEM_HOST_OBSERVER_PORT is unset, host mode auto-discovers by probing 127.0.0.1:37777 then 37778 (skipping the worker port). If neither serves an OpenAI-compatible endpoint, the install fails with this error, because host mode explicitly never starts an observer itself — you must already run one.

Source

Thrown at src/npx-cli/cmem-memory-credentials.ts:264

    const status = probe(configured);
    if (status === 'observer') return String(configured);
    if (status === 'occupied') {
      throw new HostObserverUnavailableError(
        `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.`,
      );
    }
    throw new HostObserverUnavailableError(
      `CLAUDE_MEM_HOST_OBSERVER_PORT=${configured} has nothing listening. Start your OpenAI-compatible observer on that port, then rerun with --provider host.`,
    );
  }

  const candidates = hostObserverCandidatePorts(workerPort, env);
  for (const port of candidates) {
    const status = probe(port);
    if (status === 'observer') return String(port);
  }

  throw new HostObserverUnavailableError(
    `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.`,
  );
}

export function buildHostObserverSettings(
  observerModel: 'cursor' | 'grok-bot',
  settings: SettingsLike,
  env: NodeJS.ProcessEnv = process.env,
  probe?: HostObserverPortProbe,
): Record<string, string> {
  const workerPort = parsePort(settings.CLAUDE_MEM_WORKER_PORT)
    ?? nonEmptyString(settings.CLAUDE_MEM_WORKER_PORT)
    ?? undefined;
  const port = resolveHostObserverPort(workerPort, env, probe ?? probeHostObserverPortSync);
  return {
    CLAUDE_MEM_PROVIDER: 'openrouter',
    CLAUDE_MEM_OPENROUTER_BASE_URL: `http://127.0.0.1:${port}/v1`,
    CLAUDE_MEM_OPENROUTER_MODEL: observerModel,

View on GitHub (pinned to 8bc631a71a)

Solutions

Start your OpenAI-compatible observer (the default candidates are 37777 or 37778) and rerun with --provider host
If your observer uses another port, set CLAUDE_MEM_HOST_OBSERVER_PORT to it: export CLAUDE_MEM_HOST_OBSERVER_PORT=4141
Confirm with curl http://127.0.0.1:37777/v1/models (and 37778) whether anything is reachable
Pick a different provider (e.g. --provider claude) if you do not intend to run a host observer

Example fix

// before
npx claude-mem install --provider host   # nothing on 37777/37778
// after
export CLAUDE_MEM_HOST_OBSERVER_PORT=4141  # where your observer listens
npx claude-mem install --provider host

Defensive patterns

Strategy: retry

Validate before calling

for (const p of [37777, 37778]) {
  const ok = await fetch(`http://127.0.0.1:${p}/v1/models`).then(r => r.ok).catch(() => false);
  if (ok) { process.env.CLAUDE_MEM_HOST_OBSERVER_PORT = String(p); break; }
}

Try / catch

try {
  const port = resolveHostObserverPort(workerPort, env);
} catch (e) {
  if (e instanceof HostObserverUnavailableError && e.message.startsWith('No OpenAI-compatible host observer')) {
    // start observer, optionally set CLAUDE_MEM_HOST_OBSERVER_PORT, and retry
  } else throw e;
}

Prevention

Run your observer on the default ports 37777/37778 so auto-discovery finds it
If it uses another port, always set CLAUDE_MEM_HOST_OBSERVER_PORT explicitly
Remember host mode never starts an observer — provision one yourself before install

When it happens

Trigger: Running `npx claude-mem install --provider host` with no CLAUDE_MEM_HOST_OBSERVER_PORT env var while nothing OpenAI-compatible is listening on the candidate ports (37777/37778).

Common situations: First-time host-mode setup where the user assumed claude-mem would launch an observer; observer running on a non-default port; observer crashed since a previous successful install.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

AI-assisted analysis of thedotmack/claude-mem@8bc631a71a (2026-09-09). Data as JSON: /api/errors/df91c2983e6189f7. Report an issue: GitHub.