CherryHQ/cherry-studio · error · Error

npx not found in PATH and bundled bun is not available. This

Error message

npx not found in PATH and bundled bun is not available. This may indicate an installation issue.
Please either:
1. Install Node.js (which includes npx) from https://nodejs.org
2. Run the MCP dependencies installer from Settings
3. Restart the application if you recently installed Node.js

What it means

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.

Source

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

                if (await isBinaryExists('bun')) {
                  // Fall back to bundled bun
                  cmd = await getBinaryPath('bun')
                  getServerLogger(server).info(`Using bundled bun as fallback (npx not found in PATH)`, {
                    command: cmd
                  })

                  // Transform args for bun x format
                  if (args && args.length > 0) {
                    if (!args.includes('-y')) {
                      args.unshift('-y')
                    }
                    if (!args.includes('x')) {
                      args.unshift('x')
                    }
                  }
                } else {
                  // Neither npx nor bun available
                  throw new Error(
                    'npx not found in PATH and bundled bun is not available. This may indicate an installation issue.\n' +
                      'Please either:\n' +
                      '1. Install Node.js (which includes npx) from https://nodejs.org\n' +
                      '2. Run the MCP dependencies installer from Settings\n' +
                      '3. Restart the application if you recently installed Node.js'
                  )
                }
              }

              if (server.registryUrl) {
                connectEnv.NPM_CONFIG_REGISTRY = server.registryUrl

                // if the server name is mcp-auto-install, use the mcp-registry.json file in the bin directory
                if (server.name.includes('mcp-auto-install')) {
                  const binPath = await getBinaryPath()
                  await fs.mkdir(binPath, { recursive: true })
                  connectEnv.MCP_REGISTRY_PATH = path.join(binPath, '..', 'config', 'mcp-registry.json')
                }

View on GitHub (pinned to 726446b54c)

Solutions

1. Install Node.js (includes npx) from https://nodejs.org and restart the application
2. Run the MCP dependencies installer from Settings (downloads bundled bun and other binaries)
3. If Node.js is installed but not detected, ensure it's in the system PATH (not just the user's interactive shell profile)
4. On macOS, if using nvm, add the Node.js path to /etc/paths or launch the app from a terminal that sourced nvm

import { findExecutableInEnv } from '...'

async function canRunNpxServer(): Promise<boolean> {
  return (await findExecutableInEnv('npx')) !== null || await isBinaryExists('bun')
}

// Before connecting
if (server.command === 'npx' && !(await canRunNpxServer())) {
  throw new Error('Node.js (npx) is required but not found. Install from https://nodejs.org')
}

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

When it happens

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

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

Related errors

• ${effectiveCommand} not found in PATH and bundled version is
• Failed to create provider "${id}"
• Path traversal detected: target path must be direct child of
• Unsafe DXT entry path (zip-slip): ${name}
• Invalid command: command must be a non-empty string

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