{"record":{"id":"7336acecd21aa8d0","repo":"thedotmack/claude-mem","slug":"uvx-executable-not-found-for-chroma-mcp-uvxspaw","errorCode":null,"errorMessage":"uvx executable not found for chroma-mcp (${uvxSpawnCommand})","messagePattern":"uvx executable not found for chroma-mcp \\((.+?)\\)","errorType":"exception","errorClass":"ChromaUnavailableError","httpStatus":null,"severity":"error","filePath":"src/services/sync/ChromaMcpManager.ts","lineNumber":182,"sourceCode":"    this.assertConnectionNotCancelled(connectionGeneration);\n\n    const localChromaDataDir = this.getLocalPersistentChromaDataDir();\n    const commandArgs = this.buildCommandArgs(localChromaDataDir);\n    const uvxPreflightEnv = ChromaMcpManager.getUvxPreflightEnv();\n    getSupervisor().assertCanSpawn('chroma mcp');\n\n    // Spawn uvx DIRECTLY (no `cmd.exe` shell wrapper). On Windows, routing through\n    // cmd.exe makes it parse the `>`/`<` in the dep-override specs as shell\n    // redirection before uvx sees them; a shell-less spawn passes them literally.\n    // resolveUvxCommand returns the absolute uvx.exe path on Windows (Node won't\n    // PATHEXT-resolve a bare `uvx`) and bare `uvx` elsewhere (#2696).\n    const uvxSpawnCommand = ChromaMcpManager.resolveUvxCommand();\n    const uvxSpawnArgs = commandArgs;\n\n    if (!ChromaMcpManager.isUvxAvailable(uvxSpawnCommand, uvxPreflightEnv, process.platform)) {\n      const message = `uvx executable not found for chroma-mcp (${uvxSpawnCommand})`;\n      recordUvxVectorSearchUnavailable(message);\n      throw new ChromaUnavailableError(message);\n    }\n\n    const spawnEnvironment = this.getSpawnEnv(uvxPreflightEnv);\n\n    await this.prewarmChromaMcp(uvxSpawnCommand, uvxSpawnArgs, spawnEnvironment, connectionGeneration);\n    this.assertConnectionNotCancelled(connectionGeneration);\n\n    clearDependencyStatus('uvx');\n\n    logger.info('CHROMA_MCP', 'Connecting to chroma-mcp via MCP stdio', {\n      command: uvxSpawnCommand,\n      args: uvxSpawnArgs.join(' ')\n    });\n\n    try {\n      if (localChromaDataDir) {\n        this.acquireChromaWriterLock(localChromaDataDir);\n      }","sourceCodeStart":164,"sourceCodeEnd":200,"githubUrl":"https://github.com/thedotmack/claude-mem/blob/d768ba364302d12b76e69e4f021f0bb1d2d50ed6/src/services/sync/ChromaMcpManager.ts#L164-L200","documentation":"Before spawning chroma-mcp, connectInternal() calls resolveUvxCommand() and runs isUvxAvailable() (a platform-aware PATH probe). If uvx cannot be found/resolved, it records the dependency-health status and throws ChromaUnavailableError (503 CHROMA_UNAVAILABLE) with the probed command. uvx (from the uv package) is required because chroma-mcp is launched via `uvx chroma-mcp`.","triggerScenarios":"The uv/uvx executable is not installed or not on PATH (or getUvxBinDirs() returns locations that don't contain it) at the time the manager tries to start chroma-mcp. On Windows, resolveUvxCommand returns the expected absolute uvx.exe path which does not exist.","commonSituations":"Fresh machine without uv installed; uv installed for a different user/shell so the worker's PATH lacks it; PATH was sanitized (sanitizeEnv) stripping the uv bin dir; uvx exists but the platform probe rejects it (e.g. not executable); broken uv install.","solutions":["Install uv (which provides uvx) per its official instructions and ensure it is on PATH for the user/account running the worker.","Confirm `uvx --version` works in the same shell/env as the claude-mem worker.","If uvx lives in a non-standard dir, add it via the uvx bin dirs configuration so getUvxBinDirs() includes it.","Reinstall uv if the binary is present but corrupt/non-executable, then restart the worker."],"exampleFix":"# before\nuvx --version  # command not found\n# worker throws: uvx executable not found for chroma-mcp (uvx)\n\n# after\ncurl -LsSf https://astral.sh/uv/install.sh | sh   # installs uv/uvx\nexec $SHELL\nuvx --version  # uvx 0.x\n# restart worker","handlingStrategy":"validation","validationCode":"import { execFileSync } from 'child_process';\n\nfunction uvxAvailable(): boolean {\n  try {\n    execFileSync('uvx', ['--version'], { stdio: 'ignore' });\n    return true;\n  } catch { return false; }\n}","typeGuard":"import { ChromaUnavailableError } from '../worker/search/errors.js';\n\nfunction isUvxMissing(e: unknown): boolean {\n  return e instanceof ChromaUnavailableError && /uvx executable not found/i.test(e.message);\n}","tryCatchPattern":"try {\n  await chromaManager.search(query);\n} catch (e) {\n  if (e instanceof ChromaUnavailableError && /uvx executable not found/i.test(e.message)) {\n    logger.warn('CHROMA', 'uvx not installed; vector search disabled. Install uv to enable.', {});\n    return await ftsSearch(query);\n  }\n  throw e;\n}","preventionTips":["Install uv (provides uvx) on every host that runs the worker, on PATH for that user.","Run `uvx --version` as a preflight in deployment scripts.","If vector search is optional, always provide an FTS fallback path."],"tags":["chroma","uvx","dependency","vector-search","filesystem","path"],"backgroundTag":null,"analyzedSha":"d768ba364302d12b76e69e4f021f0bb1d2d50ed6","analyzedAt":"2026-08-12T23:52:55.241Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}