thedotmack/claude-mem · warning

Dependency preflight found degraded optional setup

Error message

Dependency preflight found degraded optional setup

What it means

At worker startup, runWorkerDependencyPreflight() probes optional dependencies (each status carries dependency, kind, message) and marks the setup degraded if any are unhealthy. The worker still starts, but features backed by the missing pieces (search, embedding, or a platform CLI) will not work. This warning lists exactly which dependencies are degraded.

Source

Thrown at src/services/worker-service.ts:465

    try {
      logger.info('WORKER', 'Background initialization starting...');

      const { ModeManager } = await import('./domain/ModeManager.js');
      const { SettingsDefaultsManager } = await import('../shared/SettingsDefaultsManager.js');
      const { USER_SETTINGS_PATH } = await import('../shared/paths.js');

      const settings = SettingsDefaultsManager.loadFromFile(USER_SETTINGS_PATH);

      const modeId = settings.CLAUDE_MEM_MODE;
      ModeManager.getInstance().loadMode(modeId);
      logger.info('SYSTEM', `Mode loaded: ${modeId}`);

      const dependencyHealth = runWorkerDependencyPreflight({
        settings,
        classifyClaudeError,
      });
      if (dependencyHealth.degraded) {
        logger.warn('SYSTEM', 'Dependency preflight found degraded optional setup', {
          statuses: dependencyHealth.statuses.map(status => ({
            dependency: status.dependency,
            kind: status.kind,
            message: status.message,
          })),
        });
      } else {
        logger.info('SYSTEM', 'Dependency preflight passed');
      }

      logger.info('WORKER', 'Checking for one-time CWD remap...');
      runOneTimeCwdRemap();

      const chromaEnabled = settings.CLAUDE_MEM_CHROMA_ENABLED !== 'false';
      if (chromaEnabled) {
        this.chromaMcpManager = ChromaMcpManager.getInstance();
        logger.info('SYSTEM', 'ChromaMcpManager initialized (lazy - connects on first use)');
      } else {

View on GitHub (pinned to e2d1df569a)

Solutions

1. Read the `statuses` array in the log entry — each entry's `dependency` and `message` name the exact broken piece
2. Install or fix the named dependency (e.g. `curl -LsSf https://astral.sh/uv/install.sh | sh`, install bun, re-run CLI login)
3. Restart the worker and confirm the log now says 'Dependency preflight passed'

import { commandExists } from './checks.js';

async function assertOptionalDeps(): Promise<void> {
  for (const bin of ['bun', 'uv', 'claude']) {
    if (!(await commandExists(bin))) {
      console.warn(`optional dependency missing: ${bin} — related features will be degraded`);
    }
  }
}

When it happens

Trigger: uv missing so the Chroma/embedding Python side cannot start; bun not installed; claude or codex CLI absent or not authenticated; a dependency present but failing its probe (wrong version, broken PATH).

Common situations: Fresh machine where only some prerequisites were installed; PATH differences between the shell that installed claude-mem and the environment spawning the worker; CLI auth token expired after initial setup.

Related errors

• Service initializing
• Live PID detected but worker did not become ready before tim
• Worker is alive but readiness timed out — proceeding anyway
• `server ${commandLabel}` is a server runtime command, but CL
• server startup configuration is invalid: - ${line}

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