thedotmack/claude-mem · error

[install] Worker shutdown failed

Error message

[install] Worker shutdown failed: ${message}

What it means

During `claude-mem install`, the installer attempts to shut down any running worker before (re)installing. If worker shutdown fails with any error other than InstallAbortError, the CLI reports 'Worker shutdown failed' and records an ABORT-severity installer error with remediation guidance. It is fatal to that install run because a lingering worker would conflict with the new install.

Solutions

1. Run `npx claude-mem stop`, verify the worker process has exited, then run `npx claude-mem install` again (per the built-in remediation).
2. If `stop` fails, find and kill the worker process manually (ps/kill by PID or port), remove stale PID files, then reinstall.
3. Reboot or clear leftover runtime state if the worker keeps respawning, then reinstall.

Example fix

// before: install aborts because worker won't stop
npx claude-mem install
// error: [install] Worker shutdown failed: ...
// after
npx claude-mem stop
npx claude-mem install

// Before installing, verify no worker is running
import { execSync } from 'node:child_process';
try { execSync('npx claude-mem status', { stdio: 'pipe' }); } catch { /* worker not running */ }

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

try {
  await stopWorker();
} catch (error) {
  if (error instanceof InstallAbortError) throw error;
  console.warn('Worker shutdown failed:', error instanceof Error ? error.message : String(error));
  // remediate: npx claude-mem stop, verify exit, reinstall
}

When it happens

Trigger: Calling runInstall when a claude-mem worker process is running and the stop/shutdown call throws — e.g. worker process hung and refuses SIGTERM, PID file stale, or IPC to the worker fails.

Common situations: Upgrading/reinstalling while an old worker is still alive; orphaned worker from a previous crash; stale PID/port state after system reboot; permissions preventing signal delivery.

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 failed
• API key prompt cancelled — leaving existing configuration…
• Cannot lazy-spawn worker: worker-service.cjs not found in…
• Claude CLI preflight failed
• claude-mem: could not read

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

Appendix: source

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

      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 d8bc9755e7)