thedotmack/claude-mem · warning

[uninstall] Worker shutdown attempt failed:

Error message

[uninstall] Worker shutdown attempt failed:

What it means

Before removing files, runUninstallCommand() calls shutdownWorkerAndWait(CLAUDE_MEM_WORKER_PORT, 10000) to stop the background worker service. Any throw, such as the worker HTTP endpoint failing, a shutdown request error, or the worker not stopping within the 10-second budget, is caught and warned; uninstall continues, so the worker can still be alive after uninstall completes.

Source

Thrown at src/npx-cli/commands/uninstall.ts:278

    const shouldContinue = await p.confirm({
      message: 'Are you sure you want to uninstall claude-mem?',
      initialValue: false,
    });

    if (p.isCancel(shouldContinue) || !shouldContinue) {
      p.cancel('Uninstall cancelled.');
      return;
    }
  }

  const workerPort = SettingsDefaultsManager.get('CLAUDE_MEM_WORKER_PORT');
  try {
    const result = await shutdownWorkerAndWait(workerPort, 10000);
    if (result.workerWasRunning) {
      p.log.info('Worker service stopped.');
    }
  } catch (error: unknown) {
    console.warn('[uninstall] Worker shutdown attempt failed:', error instanceof Error ? error.message : String(error));
  }

  // #2568 — server-runtime teardown. Gated on the installed/selected runtime so
  // the worker uninstall path is completely unchanged. The bundled Docker
  // compose stack lives under the marketplace dir; if it's present we treat the
  // stack as locally managed and instruct teardown (the actual `docker compose
  // down -v` is an operator/CI side effect, not run from this Node process).
  const selectedRuntime = readSelectedRuntime();
  if (selectedRuntime === 'server') {
    if (existsSync(join(marketplaceDirectory(), 'docker-compose.yml'))) {
      p.log.info(
        'Server runtime detected. Tear down the bundled stack with '
          + '`docker compose down -v --remove-orphans` (stops + removes pg + redis/valkey).',
      );
    } else {
      p.log.info('Server runtime detected (externally managed stack — leaving Docker/pg/redis untouched).');
    }
    clearServerRuntimeSettings(SERVER_RUNTIME_SETTINGS_KEYS);

View on GitHub (pinned to e2d1df569a)

Solutions

1. Check for a survivor after uninstall: lsof -i :<port> or ps aux | grep claude-mem, and kill it
2. Verify CLAUDE_MEM_WORKER_PORT in ~/.claude/settings.json matches the port the worker actually uses
3. Re-run `npx claude-mem uninstall` once the worker is stopped or healthy
4. A reboot also clears a wedged worker if the files are already removed

function isErrnoException(error: unknown): error is NodeJS.ErrnoException {
  return error instanceof Error && typeof (error as NodeJS.ErrnoException).code === 'string';
}

try {
  const result = await shutdownWorkerAndWait(workerPort, 10_000);
  if (result.workerWasRunning) p.log.info('Worker service stopped.');
} catch (error) {
  if (isErrnoException(error) && ['ECONNREFUSED', 'ETIMEDOUT', 'ECONNRESET'].includes(error.code)) {
    // worker gone or wedged: find and kill the process by port instead of retrying HTTP
  } else {
    console.warn('[uninstall] Worker shutdown attempt failed:', error instanceof Error ? error.message : String(error));
  }
}

When it happens

Trigger: `npx claude-mem uninstall` when the worker is wedged by a stuck job, CLAUDE_MEM_WORKER_PORT in settings no longer matches the running worker, the worker needs more than 10 seconds to drain and exit, or it already died in a way that raises instead of reporting workerWasRunning=false.

Common situations: Worker stuck mid-compression or embedding job; the port changed manually after install; machine resumed from sleep with a half-dead worker process.

Related errors

• Graceful shutdown deadline exceeded — proceeding
• Unknown Claude model: ${options.model}. Allowed: ${[...allow
• Failed to install Bun. Please install manually: ${manualInst
• Shutdown request returned error
• Port did not free up after shutdown

AI-assisted analysis of thedotmack/claude-mem@e2d1df569a (2026-08-20). Data as JSON: /api/errors/e16670daaf0995c1. Report an issue: GitHub.