{"record":{"id":"2bde5cffa5735723","repo":"thedotmack/claude-mem","slug":"chroma-mcp-prewarm-failed-errormessage","errorCode":null,"errorMessage":"chroma-mcp prewarm failed: ${errorMessage}","messagePattern":"chroma-mcp prewarm failed: (.+?)","errorType":"exception","errorClass":"ChromaUnavailableError","httpStatus":null,"severity":"error","filePath":"src/services/sync/ChromaMcpManager.ts","lineNumber":693,"sourceCode":"        ...(stderr ? { stderrTail: stderr } : {})\n      });\n\n      if (pid) {\n        try {\n          await ChromaMcpManager.killProcessTree(pid);\n        } catch (killError) {\n          logger.debug('CHROMA_MCP', 'prewarm process tree kill finished (best-effort)', {\n            pid,\n            error: killError instanceof Error ? killError.message : String(killError)\n          });\n        }\n      } else {\n        try { child.kill('SIGKILL'); } catch { /* already dead */ }\n      }\n\n      const unavailableMessage = `chroma-mcp prewarm failed: ${errorMessage}`;\n      recordUvxVectorSearchUnavailable(unavailableMessage);\n      throw new ChromaUnavailableError(unavailableMessage, error instanceof Error ? error : undefined);\n    } finally {\n      if (timeoutId) {\n        clearTimeout(timeoutId);\n      }\n      if (this.activePrewarmChild === child) {\n        this.activePrewarmChild = null;\n      }\n    }\n  }\n\n  async callTool(toolName: string, toolArguments: Record<string, unknown>): Promise<unknown> {\n    if (!this.serializeMutations || !ChromaMcpManager.isMutationTool(toolName)) {\n      return this.callToolUnqueued(toolName, toolArguments);\n    }\n    if (!this.acceptingLocalMutations) {\n      throw new ChromaUnavailableError('Local Chroma mutations are unavailable after shutdown begins');\n    }\n","sourceCodeStart":675,"sourceCodeEnd":711,"githubUrl":"https://github.com/thedotmack/claude-mem/blob/d768ba364302d12b76e69e4f021f0bb1d2d50ed6/src/services/sync/ChromaMcpManager.ts#L675-L711","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the logged stderrTail/stdoutTail for the actual subprocess error (Python traceback, ModuleNotFoundError, etc.) and address that root cause.","Verify uvx is installed and functional: run `uvx --version` and `uvx chroma-mcp --help` manually as the same user.","If prewarm timed out, raise the prewarm timeout configuration or warm the uvx cache ahead of time so the package is already present.","Clear a corrupted uv cache / venv (uv cache clean, remove the chroma-mcp venv) so uvx re-provisions a clean environment.","Ensure network/proxy access for the initial uvx package fetch, or pre-install chroma-mcp into the target environment."],"exampleFix":"// before: prewarm hits a cold uvx with no cache and a short timeout\nprewarmTimeoutMs = 15000;\n// after: pre-warm the tool cache and allow longer cold start\nawait exec('uvx --quiet chroma-mcp --help'); // prime cache\nprewarmTimeoutMs = 60000;","handlingStrategy":"try-catch","validationCode":"// Pre-flight: confirm uvx can resolve chroma-mcp before starting the manager\nimport { execFileSync } from 'node:child_process';\nfunction uvxAvailable(): boolean {\n  try { execFileSync('uvx', ['--version'], { stdio: 'ignore', timeout: 5000 }); return true; }\n  catch { return false; }\n}","typeGuard":"function isPrewarmFailure(e: unknown): boolean {\n  return e instanceof Error && /chroma-mcp prewarm failed/i.test(e.message);\n}","tryCatchPattern":"try { await manager.prewarm(); }\ncatch (e) {\n  if (isPrewarmFailure(e)) { markVectorSearchUnavailable(e.message); /* run without semantic search */ return; }\n  throw e;\n}","preventionTips":["Pre-install/prime the uvx cache for chroma-mcp during setup so cold starts are fast.","Set a prewarm timeout generous enough for first-time package download.","Keep uv and a working Python environment available to the plugin user.","Capture stderr from the prewarm failure log to fix the underlying subprocess error."],"tags":["chroma","uvx","subprocess","prewarm","python","vector-search"],"backgroundTag":null,"analyzedSha":"d768ba364302d12b76e69e4f021f0bb1d2d50ed6","analyzedAt":"2026-08-12T23:52:55.241Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}