thedotmack/claude-mem · error · ChromaUnavailableError

uvx executable not found for chroma-mcp (${uvxSpawnCommand})

Error message

uvx executable not found for chroma-mcp (${uvxSpawnCommand})

What it means

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`.

Source

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

    this.assertConnectionNotCancelled(connectionGeneration);

    const localChromaDataDir = this.getLocalPersistentChromaDataDir();
    const commandArgs = this.buildCommandArgs(localChromaDataDir);
    const uvxPreflightEnv = ChromaMcpManager.getUvxPreflightEnv();
    getSupervisor().assertCanSpawn('chroma mcp');

    // Spawn uvx DIRECTLY (no `cmd.exe` shell wrapper). On Windows, routing through
    // cmd.exe makes it parse the `>`/`<` in the dep-override specs as shell
    // redirection before uvx sees them; a shell-less spawn passes them literally.
    // resolveUvxCommand returns the absolute uvx.exe path on Windows (Node won't
    // PATHEXT-resolve a bare `uvx`) and bare `uvx` elsewhere (#2696).
    const uvxSpawnCommand = ChromaMcpManager.resolveUvxCommand();
    const uvxSpawnArgs = commandArgs;

    if (!ChromaMcpManager.isUvxAvailable(uvxSpawnCommand, uvxPreflightEnv, process.platform)) {
      const message = `uvx executable not found for chroma-mcp (${uvxSpawnCommand})`;
      recordUvxVectorSearchUnavailable(message);
      throw new ChromaUnavailableError(message);
    }

    const spawnEnvironment = this.getSpawnEnv(uvxPreflightEnv);

    await this.prewarmChromaMcp(uvxSpawnCommand, uvxSpawnArgs, spawnEnvironment, connectionGeneration);
    this.assertConnectionNotCancelled(connectionGeneration);

    clearDependencyStatus('uvx');

    logger.info('CHROMA_MCP', 'Connecting to chroma-mcp via MCP stdio', {
      command: uvxSpawnCommand,
      args: uvxSpawnArgs.join(' ')
    });

    try {
      if (localChromaDataDir) {
        this.acquireChromaWriterLock(localChromaDataDir);
      }

View on GitHub (pinned to d768ba3643)

Solutions

1. Install uv (which provides uvx) per its official instructions and ensure it is on PATH for the user/account running the worker.
2. Confirm `uvx --version` works in the same shell/env as the claude-mem worker.
3. If uvx lives in a non-standard dir, add it via the uvx bin dirs configuration so getUvxBinDirs() includes it.
4. Reinstall uv if the binary is present but corrupt/non-executable, then restart the worker.

Example fix

# before
uvx --version  # command not found
# worker throws: uvx executable not found for chroma-mcp (uvx)

# after
curl -LsSf https://astral.sh/uv/install.sh | sh   # installs uv/uvx
exec $SHELL
uvx --version  # uvx 0.x
# restart worker

import { execFileSync } from 'child_process';

function uvxAvailable(): boolean {
  try {
    execFileSync('uvx', ['--version'], { stdio: 'ignore' });
    return true;
  } catch { return false; }
}

import { ChromaUnavailableError } from '../worker/search/errors.js';

function isUvxMissing(e: unknown): boolean {
  return e instanceof ChromaUnavailableError && /uvx executable not found/i.test(e.message);
}

try {
  await chromaManager.search(query);
} catch (e) {
  if (e instanceof ChromaUnavailableError && /uvx executable not found/i.test(e.message)) {
    logger.warn('CHROMA', 'uvx not installed; vector search disabled. Install uv to enable.', {});
    return await ftsSearch(query);
  }
  throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Unable to acquire Chroma writer lock at ${lockPath}: ${error
• Chroma writer lock at ${lockPath} is unreadable; refusing to
• Unable to remove stale Chroma writer lock at ${lockPath}: ${
• chroma-mcp prewarm failed: ${errorMessage}
• chroma-mcp connection in backoff (${Math.ceil((RECONNECT_BAC

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