thedotmack/claude-mem · error

Worker shutdown failed: ${message}

Error message

Worker shutdown failed: ${message}

What it means

During `npx claude-mem install`, the installer attempts to stop a running worker service before completing installation. If the shutdown step throws any error (other than InstallAbortError, which is re-thrown), the installer logs 'Worker shutdown failed: <message>' and records an installerError with severity ABORT, component 'worker-shutdown', with remediation pointing at `npx claude-mem stop`. This is fatal because a worker that cannot be shut down can leave stale processes or port conflicts that corrupt the install.

Source

Thrown at src/npx-cli/commands/install.ts:1881

      spinner?.error('Running worker did not stop; refusing to overwrite its live configuration.');
      installerError(ErrorSeverity.ABORT, {
        component: 'worker-shutdown',
        phase,
        cause: new Error('The existing worker did not stop within 10 seconds.'),
        remediation: 'Run `npx claude-mem stop`, verify it exits, then run `npx claude-mem install` again.',
      }, summary);
    }

    const stopMessage = result.workerWasRunning
      ? 'Stopped running worker before configuration cutover.'
      : 'No worker running — proceeding.';
    if (spinner) spinner.stop(stopMessage);
    else if (result.workerWasRunning) log.info(stopMessage);
  } catch (error: unknown) {
    if (error instanceof InstallAbortError) throw error;
    const message = error instanceof Error ? error.message : String(error);
    if (spinner) spinner.error(`Worker shutdown failed: ${message}`);
    else console.warn('[install] Worker shutdown failed:', message);
    installerError(ErrorSeverity.ABORT, {
      component: 'worker-shutdown',
      phase,
      cause: error,
      remediation: 'Run `npx claude-mem stop`, verify it exits, then run `npx claude-mem install` again.',
    }, summary);
  }
}

function validateNonInteractiveProvider(
  options: InstallOptions,
  summary: InstallSummary,
): void {
  if (isInteractive) return;

  if (!options.provider) {
    installerError(ErrorSeverity.ABORT, {
      component: 'provider-selection',

View on GitHub (pinned to 8bc631a71a)

Solutions

1. Run `npx claude-mem stop` and verify the worker process exits.
2. Re-run `npx claude-mem install` after confirming the worker is gone.
3. If the process will not die, kill it manually (kill <pid> on macOS/Linux, taskkill /F /PID <pid> on Windows).
4. Check nothing else is bound to CLAUDE_MEM_WORKER_PORT; change the port in settings if there is a conflict.
5. Retry the install; if it persists, capture the underlying message from the installerError output for a bug report.

Example fix

// before
npx claude-mem install   // fails: Worker shutdown failed: ...
// after
npx claude-mem stop       # verify it exits
npx claude-mem install

const port = 37777; // or settings CLAUDE_MEM_WORKER_PORT
const res = await fetch(`http://127.0.0.1:${port}/health`).catch(() => null);
if (res && res.ok) console.log('worker running — run npx claude-mem stop before install');

function isAbort(e: unknown): e is InstallAbortError { return e instanceof InstallAbortError; }

try {
  await shutdownWorkerAndWait(port, 10000);
} catch (error) {
  if (error instanceof InstallAbortError) throw error;
  console.error('Worker shutdown failed:', error instanceof Error ? error.message : String(error));
  // remediation: npx claude-mem stop, verify exit, retry install
}

When it happens

Trigger: A worker process is running during install and the shutdown call throws — the worker port is unreachable in a way that raises, the process refuses to stop, an IPC/socket error occurs during the stop request, or an unexpected exception escapes the shutdown routine inside the install command.

Common situations: Stale worker from a previously crashed session holding CLAUDE_MEM_WORKER_PORT; worker process hung and unresponsive; permission issues killing the worker process; version mismatch where the running worker no longer understands the shutdown protocol; antivirus/firewall interfering with the stop request.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• Worker shutdown attempt failed: ${error instanceof Error ? e
• [uninstall] Worker shutdown attempt failed:
• Shutdown request returned error
• Shutdown already in progress — ignoring re-entrant shutdown
• Graceful shutdown deadline exceeded — proceeding

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