CherryHQ/cherry-studio · error · Error

${effectiveCommand} not found in PATH and bundled version is

Error message

${effectiveCommand} not found in PATH and bundled version is not available. This may indicate an installation issue.
Please either:
1. Install uv from https://github.com/astral-sh/uv
2. Run the MCP dependencies installer from Settings
3. Restart the application if you recently installed ${effectiveCommand}

What it means

Thrown when a server's effective command is 'uv' or 'uvx', but the binary is not found in the system PATH (findExecutableInEnv returns null) and the bundled version is also unavailable (isBinaryExists returns false). uv/uvx is used to launch Python-based MCP servers.

Source

Thrown at src/main/ai/mcp/McpRuntimeService.ts:643

              const uvPath = await findExecutableInEnv(effectiveCommand)

              if (uvPath) {
                // Use system uvx/uv
                cmd = uvPath
                getServerLogger(server).debug(`Using system ${effectiveCommand}`, { command: cmd })
              } else {
                // System command not found, try bundled version as fallback
                getServerLogger(server).debug(`System ${effectiveCommand} not found, checking for bundled version`)

                if (await isBinaryExists(effectiveCommand)) {
                  // Fall back to bundled version
                  cmd = await getBinaryPath(effectiveCommand)
                  getServerLogger(server).info(`Using bundled ${effectiveCommand} as fallback (not found in PATH)`, {
                    command: cmd
                  })
                } else {
                  // Neither system nor bundled available
                  throw new Error(
                    `${effectiveCommand} not found in PATH and bundled version is not available. This may indicate an installation issue.\n` +
                      'Please either:\n' +
                      '1. Install uv from https://github.com/astral-sh/uv\n' +
                      '2. Run the MCP dependencies installer from Settings\n' +
                      `3. Restart the application if you recently installed ${effectiveCommand}`
                  )
                }
              }

              if (server.registryUrl) {
                connectEnv.UV_DEFAULT_INDEX = server.registryUrl
                connectEnv.PIP_INDEX_URL = server.registryUrl
              }
            } else {
              // For any other command (e.g., globally installed npm packages, standalone binaries),
              // try to resolve to a full path so cross-spawn doesn't depend on a potentially
              // incomplete PATH in the environment.
              const resolved = await findCommandInShellEnv(effectiveCommand, loginShellEnv)

View on GitHub (pinned to 726446b54c)

Solutions

1. Install uv from https://github.com/astral-sh/uv (curl installer or pip install uv) and restart the app
2. Run the MCP dependencies installer from Settings to download the bundled uv binary
3. Verify uv is accessible from the login shell environment (the app reads login shell env via getShellEnv)
4. If uv is installed but not found, add its installation directory to PATH and relaunch

async function canRunUvServer(command: string): Promise<boolean> {
  if (command !== 'uv' && command !== 'uvx') return true
  return (await findExecutableInEnv(command)) !== null || await isBinaryExists(command)
}

// Before connecting
if ((server.command === 'uv' || server.command === 'uvx') && !(await canRunUvServer(server.command))) {
  throw new Error('uv is required but not found. Install from https://github.com/astral-sh/uv')
}

try {
  await runtime.getOrCreateClient(server)
} catch (e) {
  if (e instanceof Error && e.message.includes('not found in PATH')) {
    // Prompt user to install uv or run the MCP dependencies installer
    showInstallUvDialog()
    return
  }
  throw e
}

When it happens

Trigger: Connecting to an MCP server configured with command 'uv' or 'uvx' on a system where uv is not installed and the application's bundled uv binary is missing.

Common situations: Python-based MCP server configured but uv was never installed; the bundled uv binary failed to extract; uv was installed in a user-local path not visible to the Electron app's process environment.

Related errors

• npx not found in PATH and bundled bun is not available. This
• Failed to create provider "${id}"
• Provider extension "${baseId}" not found. Did you forget to
• OpenAI Compatible provider requires settings
• Path traversal detected: target path must be direct child of

AI-assisted analysis of CherryHQ/cherry-studio@726446b54c (2026-08-12). Data as JSON: /api/errors/dacd355392b19c0a. Report an issue: GitHub.