What causes "Script not found: ${bootstrapPath}" in oven-sh/bun?

Inspect the exact path in the error message and check whether it exists (`ls` it)

oven-sh/bun · error · Error

Script not found: ${bootstrapPath}

Error message

Script not found: ${bootstrapPath}

What it means

When the bootstrap option is set, machine.mjs resolves a bootstrap script next to itself — bootstrap.ps1 on Windows, ../.buildkite/Dockerfile-bootstrap.sh when the docker feature is on, otherwise bootstrap.sh — and throws if existsSync fails. The resolved absolute path is included in the message.

Source

Thrown at scripts/machine.mjs:1474

    name += `-musl`;
  }

  if (features?.length) {
    name += `-with-${features.join("-")}`;
  }

  let bootstrapPath, agentPath, dockerfilePath;
  if (bootstrap) {
    bootstrapPath = resolve(
      import.meta.dirname,
      os === "windows"
        ? "bootstrap.ps1"
        : features?.includes("docker")
          ? "../.buildkite/Dockerfile-bootstrap.sh"
          : "bootstrap.sh",
    );
    if (!existsSync(bootstrapPath)) {
      throw new Error(`Script not found: ${bootstrapPath}`);
    }
    if (ci) {
      const npx = which("bunx") || which("npx");
      if (!npx) {
        throw new Error("Executable not found: bunx or npx");
      }
      const entryPath = resolve(import.meta.dirname, "agent.mjs");
      const tmpPath = mkdtempSync(join(tmpdir(), "agent-"));
      agentPath = join(tmpPath, "agent.mjs");
      await spawnSafe($`${npx} esbuild ${entryPath} --bundle --platform=node --format=esm --outfile=${agentPath}`);
    }

    if (features?.includes("docker")) {
      dockerfilePath = resolve(import.meta.dirname, "../.buildkite/Dockerfile");

      if (!existsSync(dockerfilePath)) {
        throw new Error(`Dockerfile not found: ${dockerfilePath}`);
      }

View on GitHub (pinned to 8c5296ac45)

Solutions

Inspect the exact path in the error message and check whether it exists (`ls` it)
Restore the file in git: `git restore scripts/bootstrap.sh` (or `.buildkite/Dockerfile-bootstrap.sh`)
Run from a full clone of the repository so the relative resolution from import.meta.dirname works
Drop the bootstrap option if you do not need a bootstrapped machine

Defensive patterns

Strategy: validation

Validate before calling

import { existsSync } from "node:fs";
import { resolve, dirname } from "node:path";

const scriptDir = dirname(fileURLToPath(import.meta.url));
const candidates = [
  resolve(scriptDir, "bootstrap.sh"),
  resolve(scriptDir, "bootstrap.ps1"),
  resolve(scriptDir, "../.buildkite/Dockerfile-bootstrap.sh"),
];
if (bootstrapRequested && !candidates.some(existsSync)) {
  throw new Error("Bootstrap scripts missing — run from a full checkout");
}

Prevention

Run machine.mjs from a complete clone; avoid sparse checkouts that drop scripts/ or .buildkite/
In CI, add a checkout-integrity step listing required files before invoking machine tasks

When it happens

Trigger: Passing the bootstrap flag in a checkout where the target file was deleted, moved, or never checked out (sparse checkout / partial archive of the repo), or running a copied machine.mjs without its sibling scripts.

Common situations: Sparse CI checkout that excludes scripts/bootstrap.sh; a stale branch after the bootstrap files were reorganized into .buildkite/; running the script from an extracted tarball of only part of the repo.

Related errors

AI-assisted analysis of oven-sh/bun@8c5296ac45 (2026-08-16). Data as JSON: /api/errors/ca1fbb946b7a6964. Report an issue: GitHub.