{"record":{"id":"dacd355392b19c0a","repo":"CherryHQ/cherry-studio","slug":"effectivecommand-not-found-in-path-and-bundled","errorCode":null,"errorMessage":"${effectiveCommand} not found in PATH and bundled version is not available. This may indicate an installation issue.\nPlease either:\n1. Install uv from https://github.com/astral-sh/uv\n2. Run the MCP dependencies installer from Settings\n3. Restart the application if you recently installed ${effectiveCommand}","messagePattern":"(.+?) not found in PATH and bundled version is not available\\. This may indicate an installation issue\\.\nPlease either:\n1\\. Install uv from https://github\\.com/astral-sh/uv\n2\\. Run the MCP dependencies installer from Settings\n3\\. Restart the application if you recently installed (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/main/ai/mcp/McpRuntimeService.ts","lineNumber":643,"sourceCode":"              const uvPath = await findExecutableInEnv(effectiveCommand)\n\n              if (uvPath) {\n                // Use system uvx/uv\n                cmd = uvPath\n                getServerLogger(server).debug(`Using system ${effectiveCommand}`, { command: cmd })\n              } else {\n                // System command not found, try bundled version as fallback\n                getServerLogger(server).debug(`System ${effectiveCommand} not found, checking for bundled version`)\n\n                if (await isBinaryExists(effectiveCommand)) {\n                  // Fall back to bundled version\n                  cmd = await getBinaryPath(effectiveCommand)\n                  getServerLogger(server).info(`Using bundled ${effectiveCommand} as fallback (not found in PATH)`, {\n                    command: cmd\n                  })\n                } else {\n                  // Neither system nor bundled available\n                  throw new Error(\n                    `${effectiveCommand} not found in PATH and bundled version is not available. This may indicate an installation issue.\\n` +\n                      'Please either:\\n' +\n                      '1. Install uv from https://github.com/astral-sh/uv\\n' +\n                      '2. Run the MCP dependencies installer from Settings\\n' +\n                      `3. Restart the application if you recently installed ${effectiveCommand}`\n                  )\n                }\n              }\n\n              if (server.registryUrl) {\n                connectEnv.UV_DEFAULT_INDEX = server.registryUrl\n                connectEnv.PIP_INDEX_URL = server.registryUrl\n              }\n            } else {\n              // For any other command (e.g., globally installed npm packages, standalone binaries),\n              // try to resolve to a full path so cross-spawn doesn't depend on a potentially\n              // incomplete PATH in the environment.\n              const resolved = await findCommandInShellEnv(effectiveCommand, loginShellEnv)","sourceCodeStart":625,"sourceCodeEnd":661,"githubUrl":"https://github.com/CherryHQ/cherry-studio/blob/726446b54cd69ffe51a276638672f6d95ca0768c/src/main/ai/mcp/McpRuntimeService.ts#L625-L661","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Install uv from https://github.com/astral-sh/uv (curl installer or pip install uv) and restart the app","Run the MCP dependencies installer from Settings to download the bundled uv binary","Verify uv is accessible from the login shell environment (the app reads login shell env via getShellEnv)","If uv is installed but not found, add its installation directory to PATH and relaunch"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"async function canRunUvServer(command: string): Promise<boolean> {\n  if (command !== 'uv' && command !== 'uvx') return true\n  return (await findExecutableInEnv(command)) !== null || await isBinaryExists(command)\n}\n\n// Before connecting\nif ((server.command === 'uv' || server.command === 'uvx') && !(await canRunUvServer(server.command))) {\n  throw new Error('uv is required but not found. Install from https://github.com/astral-sh/uv')\n}","typeGuard":null,"tryCatchPattern":"try {\n  await runtime.getOrCreateClient(server)\n} catch (e) {\n  if (e instanceof Error && e.message.includes('not found in PATH')) {\n    // Prompt user to install uv or run the MCP dependencies installer\n    showInstallUvDialog()\n    return\n  }\n  throw e\n}","preventionTips":["Run the MCP dependencies installer from Settings to download bundled uv","Install uv via the official curl installer for system-wide availability","Check that uv is in the login shell environment, not just interactive terminals"],"tags":["mcp","uv","python","dependency","environment"],"backgroundTag":null,"analyzedSha":"726446b54cd69ffe51a276638672f6d95ca0768c","analyzedAt":"2026-08-12T17:30:37.448Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}