thedotmack/claude-mem · error · ChromaUnavailableError

chroma-mcp prewarm failed: ${errorMessage}

Error message

chroma-mcp prewarm failed: ${errorMessage}

What it means

Thrown when prewarming the chroma-mcp uvx subprocess fails: the exit promise rejected (non-zero exit code, or a non-zero/null code per the close handler) or the timeout promise fired (prewarm timed out after ${timeoutMs}ms). The child is tree-killed, recordUvxVectorSearchUnavailable is called, and a ChromaUnavailableError is raised. ChromaMcpConnectionCancelledError from shutdown is re-thrown unchanged. This blocks both indexing and querying until uvx can bring chroma-mcp up.

Source

Thrown at src/services/sync/ChromaMcpManager.ts:693

        ...(stderr ? { stderrTail: stderr } : {})
      });

      if (pid) {
        try {
          await ChromaMcpManager.killProcessTree(pid);
        } catch (killError) {
          logger.debug('CHROMA_MCP', 'prewarm process tree kill finished (best-effort)', {
            pid,
            error: killError instanceof Error ? killError.message : String(killError)
          });
        }
      } else {
        try { child.kill('SIGKILL'); } catch { /* already dead */ }
      }

      const unavailableMessage = `chroma-mcp prewarm failed: ${errorMessage}`;
      recordUvxVectorSearchUnavailable(unavailableMessage);
      throw new ChromaUnavailableError(unavailableMessage, error instanceof Error ? error : undefined);
    } finally {
      if (timeoutId) {
        clearTimeout(timeoutId);
      }
      if (this.activePrewarmChild === child) {
        this.activePrewarmChild = null;
      }
    }
  }

  async callTool(toolName: string, toolArguments: Record<string, unknown>): Promise<unknown> {
    if (!this.serializeMutations || !ChromaMcpManager.isMutationTool(toolName)) {
      return this.callToolUnqueued(toolName, toolArguments);
    }
    if (!this.acceptingLocalMutations) {
      throw new ChromaUnavailableError('Local Chroma mutations are unavailable after shutdown begins');
    }

View on GitHub (pinned to d768ba3643)

Solutions

1. Check the logged stderrTail/stdoutTail for the actual subprocess error (Python traceback, ModuleNotFoundError, etc.) and address that root cause.
2. Verify uvx is installed and functional: run `uvx --version` and `uvx chroma-mcp --help` manually as the same user.
3. If prewarm timed out, raise the prewarm timeout configuration or warm the uvx cache ahead of time so the package is already present.
4. Clear a corrupted uv cache / venv (uv cache clean, remove the chroma-mcp venv) so uvx re-provisions a clean environment.
5. Ensure network/proxy access for the initial uvx package fetch, or pre-install chroma-mcp into the target environment.

Example fix

// before: prewarm hits a cold uvx with no cache and a short timeout
prewarmTimeoutMs = 15000;
// after: pre-warm the tool cache and allow longer cold start
await exec('uvx --quiet chroma-mcp --help'); // prime cache
prewarmTimeoutMs = 60000;

// Pre-flight: confirm uvx can resolve chroma-mcp before starting the manager
import { execFileSync } from 'node:child_process';
function uvxAvailable(): boolean {
  try { execFileSync('uvx', ['--version'], { stdio: 'ignore', timeout: 5000 }); return true; }
  catch { return false; }
}

function isPrewarmFailure(e: unknown): boolean {
  return e instanceof Error && /chroma-mcp prewarm failed/i.test(e.message);
}

try { await manager.prewarm(); }
catch (e) {
  if (isPrewarmFailure(e)) { markVectorSearchUnavailable(e.message); /* run without semantic search */ return; }
  throw e;
}

When it happens

Trigger: prewarmChromaMcp runs `uvx chroma-mcp ...`; the subprocess exits non-zero (import error, missing dependency, bad flag), or does not exit successfully within timeoutMs, or uvx itself is missing/broken. stderr/stdout tails are logged.

Common situations: First run on a machine without uv/uvx installed or without network to pull the chroma-mcp package; a broken Python environment (uv-managed venv corrupt); a chroma-mcp version incompatible with the configured flags; cold-start on a slow CPU where prewarm exceeds the configured timeout; corporate proxy blocking the uvx package download.

Related errors

• uvx executable not found for chroma-mcp (${uvxSpawnCommand})
• chroma-mcp transport error during "${toolName}" (retry faile
• chroma-mcp connection in backoff (${Math.ceil((RECONNECT_BAC
• Unable to acquire Chroma writer lock at ${lockPath}: ${error
• Chroma writer lock at ${lockPath} is unreadable; refusing to

AI-assisted analysis of thedotmack/claude-mem@d768ba3643 (2026-08-12). Data as JSON: /api/errors/2bde5cffa5735723. Report an issue: GitHub.