oven-sh/bun · error · Error

Usage: ./${scriptPath} [ssh|create-image|publish-image] [opt

Error message

Usage: ./${scriptPath} [ssh|create-image|publish-image] [options]

What it means

scripts/machine.mjs validates its first positional argument against /^(ssh|create-image|publish-image)$/ and throws this usage line when it does not match, including when no command was given at all. It is a command-line contract check, not a runtime failure.

Source

Thrown at scripts/machine.mjs:1367

  // Extract
  await spawnSafe(["unzip", "-o", zipPath, "-d", tmpdir()], { stdio: "inherit" });
  chmodSync(localPacker, 0o755);

  console.log(`[packer] Installed Packer ${version}`);
  return localPacker;
}

async function main() {
  const { positionals } = parseArgs({
    allowPositionals: true,
    strict: false,
  });

  const [command] = positionals;
  if (!/^(ssh|create-image|publish-image)$/.test(command)) {
    const scriptPath = relative(process.cwd(), fileURLToPath(import.meta.url));
    throw new Error(`Usage: ./${scriptPath} [ssh|create-image|publish-image] [options]`);
  }

  const { values: args } = parseArgs({
    allowPositionals: true,
    options: {
      "cloud": { type: "string", default: "aws" },
      "os": { type: "string", default: "linux" },
      "arch": { type: "string", default: "x64" },
      "distro": { type: "string" },
      "release": { type: "string" },
      "name": { type: "string" },
      "instance-type": { type: "string" },
      "image-id": { type: "string" },
      "image-name": { type: "string" },
      "cpu-count": { type: "string" },
      "memory-gb": { type: "string" },
      "disk-size-gb": { type: "string" },
      "preemptible": { type: "boolean" },

View on GitHub (pinned to 8c5296ac45)

Solutions

1. Invoke the script with one of: ssh, create-image, publish-image as the first argument
2. Put options after the subcommand (e.g. `./scripts/machine.mjs create-image --cloud=azure`)

Example fix

# before
./scripts/machine.mjs create_images

# after
./scripts/machine.mjs create-image

const COMMANDS = new Set(["ssh", "create-image", "publish-image"]);
const command = process.argv[2];
if (!COMMANDS.has(command ?? "")) {
  console.error(`Unknown command ${JSON.stringify(command)}. Valid: ${[...COMMANDS].join(" | ")}`);
  process.exit(2);
}

const isMachineCommand = (v: string | undefined): v is "ssh" | "create-image" | "publish-image" =>
  /^(ssh|create-image|publish-image)$/.test(v ?? "");

When it happens

Trigger: Running `./scripts/machine.mjs` with zero arguments, a typo like `create_images` or `publish`, or an unknown subcommand. Because the first parseArgs uses strict:false, any leading positional that is not one of the three words becomes the command and fails the regex.

Common situations: Typos in CI pipeline commands; copy-pasting an outdated subcommand after the script's CLI was renamed; forgetting that options must come after the command.

Related errors

• --${rawKey} requires a value
• Invalid boolean value: ${v}
• Cannot exec: build mode produced no executable
• Unknown config field: --${rawKey}
• usage: bun src/codegen/generate-string-map.ts <input.string-

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