npm is required to run this project (package-lock.json or pa

Error message

npm is required to run this project (package-lock.json or packageManager indicates npm).

What it means

runPkgCommand detects the package manager from the plugin project's `packageManager` field or lockfile. If detection resolves to npm (package-lock.json present or packageManager starts with "npm@") but the npm binary is not available on PATH, it throws this error rather than substituting another package manager.

Source

Thrown at packages/cli/src/exec.ts:73

  const npm = await utilityInstalled("npm")
  const pnpm = await utilityInstalled("pnpm")

  // Use the plugin's lockfile/packageManager when available, otherwise default to yarn.
  if (preferred === "pnpm") {
    if (!pnpm) {
      throw new Error(
        "pnpm is required to run this project (pnpm-lock.yaml or packageManager indicates pnpm)."
      )
    }
    const pnpmCmd =
      command === "install" ? "pnpm install" : `pnpm run ${command}`
    await exec(pnpmCmd, dir)
    return
  }

  if (preferred === "npm") {
    if (!npm) {
      throw new Error(
        "npm is required to run this project (package-lock.json or packageManager indicates npm)."
      )
    }
    const npmCmd =
      command === "install" ? `npm ${command}` : `npm run ${command}`
    await exec(npmCmd, dir)
    return
  }

  // If the project indicates yarn, use it (with npm fallback).
  if (preferred === "yarn") {
    if (yarn) {
      await exec(`yarn ${command} --ignore-engines`, dir)
      return
    }
    if (!npm) {
      throw new Error(
        "yarn is required to run this project (yarn.lock or packageManager indicates yarn)."

View on GitHub (pinned to a81a902e9a)

Solutions

Install Node.js/npm (or repair the installation) and confirm `npm --version` works
Fix PATH so the node/npm binaries directory is included in the shell/CI environment
Alternatively switch the project's detection signals (remove package-lock.json, change packageManager) to a manager that is installed
Use nvm or a Node docker image that bundles npm

Example fix

// CI before
- run: budi plugins build   # npm missing in image
// after
- uses: actions/setup-node@v4
  with: { node-version: 20 }
- run: budi plugins build

Defensive patterns

Strategy: validation

Validate before calling

const { execSync } = require("child_process")
const fs = require("fs")
function assertNpmAvailable(dir = ".") {
  const pkg = JSON.parse(fs.readFileSync(dir + "/package.json", "utf8"))
  const wantsNpm = fs.existsSync(dir + "/package-lock.json") ||
    (pkg.packageManager || "").startsWith("npm@")
  if (wantsNpm) execSync("npm --version", { stdio: "ignore" }) // throws if missing
}

Try / catch

try {
  await runPkgCommand("build", dir)
} catch (err) {
  if ((err as Error).message.startsWith("npm is required")) {
    console.error("Install Node.js/npm or fix PATH before building")
  }
  throw err
}

Prevention

Install Node.js (bundles npm) and verify `npm --version` before running budi commands
In CI, use a setup-node step before plugin builds
Don't strip PATH in sudo/containers where the CLI runs
Keep package-lock.json only if npm is the intended manager

When it happens

Trigger: Running budi plugin commands (init/build/watch/migrateSvelte5 -> runPkgCommand) in a directory with package-lock.json or "packageManager": "npm@..." while `npm --version` fails (npm not installed, PATH broken, or running inside a minimal container without Node/npm).

Common situations: Minimal Docker/CI images with node but npm removed; corrupted Node installation; running budi via a wrapper that strips PATH; plugin repo converted to npm but toolchain not updated.

Related errors

AI-assisted analysis of Budibase/budibase@a81a902e9a (2026-08-29). Data as JSON: /api/errors/d98daebd041af3df. Report an issue: GitHub.