{"record":{"id":"c6df623b78259d8e","repo":"CherryHQ/cherry-studio","slug":"npx-not-found-in-path-and-bundled-bun-is-not-avail","errorCode":null,"errorMessage":"npx not found in PATH and bundled bun is not available. This may indicate an installation issue.\nPlease either:\n1. Install Node.js (which includes npx) from https://nodejs.org\n2. Run the MCP dependencies installer from Settings\n3. Restart the application if you recently installed Node.js","messagePattern":"npx not found in PATH and bundled bun is not available\\. This may indicate an installation issue\\.\nPlease either:\n1\\. Install Node\\.js \\(which includes npx\\) from https://nodejs\\.org\n2\\. Run the MCP dependencies installer from Settings\n3\\. Restart the application if you recently installed Node\\.js","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/main/ai/mcp/McpRuntimeService.ts","lineNumber":603,"sourceCode":"                if (await isBinaryExists('bun')) {\n                  // Fall back to bundled bun\n                  cmd = await getBinaryPath('bun')\n                  getServerLogger(server).info(`Using bundled bun as fallback (npx not found in PATH)`, {\n                    command: cmd\n                  })\n\n                  // Transform args for bun x format\n                  if (args && args.length > 0) {\n                    if (!args.includes('-y')) {\n                      args.unshift('-y')\n                    }\n                    if (!args.includes('x')) {\n                      args.unshift('x')\n                    }\n                  }\n                } else {\n                  // Neither npx nor bun available\n                  throw new Error(\n                    'npx not found in PATH and bundled bun is not available. This may indicate an installation issue.\\n' +\n                      'Please either:\\n' +\n                      '1. Install Node.js (which includes npx) from https://nodejs.org\\n' +\n                      '2. Run the MCP dependencies installer from Settings\\n' +\n                      '3. Restart the application if you recently installed Node.js'\n                  )\n                }\n              }\n\n              if (server.registryUrl) {\n                connectEnv.NPM_CONFIG_REGISTRY = server.registryUrl\n\n                // if the server name is mcp-auto-install, use the mcp-registry.json file in the bin directory\n                if (server.name.includes('mcp-auto-install')) {\n                  const binPath = await getBinaryPath()\n                  await fs.mkdir(binPath, { recursive: true })\n                  connectEnv.MCP_REGISTRY_PATH = path.join(binPath, '..', 'config', 'mcp-registry.json')\n                }","sourceCodeStart":585,"sourceCodeEnd":621,"githubUrl":"https://github.com/CherryHQ/cherry-studio/blob/726446b54cd69ffe51a276638672f6d95ca0768c/src/main/ai/mcp/McpRuntimeService.ts#L585-L621","documentation":"Thrown when a server's effective command is 'npx', but npx is not found in the system PATH (via findExecutableInEnv) and the bundled bun binary is also not available (isBinaryExists('bun') returns false). The runtime uses npx to launch Node.js-based MCP servers, falling back to bundled bun's `bun x` as an alternative runner.","triggerScenarios":"Connecting to an MCP server configured with command 'npx' on a system where Node.js/npx is not installed or not in PATH, and the application's bundled bun binary is missing or not extracted.","commonSituations":"Fresh OS install without Node.js; Node.js was installed via a version manager (nvm/fnm) that doesn't populate the login shell env the app reads; the bundled bun binary failed to download during first run; PATH is not inherited correctly by the Electron app on macOS.","solutions":["Install Node.js (includes npx) from https://nodejs.org and restart the application","Run the MCP dependencies installer from Settings (downloads bundled bun and other binaries)","If Node.js is installed but not detected, ensure it's in the system PATH (not just the user's interactive shell profile)","On macOS, if using nvm, add the Node.js path to /etc/paths or launch the app from a terminal that sourced nvm"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"import { findExecutableInEnv } from '...'\n\nasync function canRunNpxServer(): Promise<boolean> {\n  return (await findExecutableInEnv('npx')) !== null || await isBinaryExists('bun')\n}\n\n// Before connecting\nif (server.command === 'npx' && !(await canRunNpxServer())) {\n  throw new Error('Node.js (npx) is required but not found. Install from https://nodejs.org')\n}","typeGuard":null,"tryCatchPattern":"try {\n  await runtime.getOrCreateClient(server)\n} catch (e) {\n  if (e instanceof Error && e.message.includes('npx not found in PATH')) {\n    // Prompt user to install Node.js or run the MCP dependencies installer\n    showInstallNodeDialog()\n    return\n  }\n  throw e\n}","preventionTips":["Run the MCP dependencies installer from Settings on first launch to ensure bundled binaries are available","Verify Node.js is in the system PATH (not just user shell profile) before launching the app","On macOS, install Node.js via the official installer rather than nvm to ensure global PATH visibility"],"tags":["mcp","npx","nodejs","dependency","environment"],"backgroundTag":null,"analyzedSha":"726446b54cd69ffe51a276638672f6d95ca0768c","analyzedAt":"2026-08-12T17:30:37.448Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}