oven-sh/bun · error · BuildError

Unknown config field: --${rawKey}

Error message

Unknown config field: --${rawKey}

What it means

scripts/build.ts maps --key=value pairs onto a PartialConfig. After handling profile/target/configFile, remaining keys must exist in boolFields or stringFields; anything else is rejected with this BuildError, and the hint enumerates every accepted field name.

Source

Thrown at scripts/build.ts:562

    }

    if (key === "target") {
      ninjaTargets.push(value);
      continue;
    }
    if (key === "configFile") {
      configFile = value;
      configureOnly = true;
      continue;
    }
    if (key === "profile") {
      profile = value;
    } else if (boolFields.has(key)) {
      (overrides as Record<string, boolean>)[key] = parseBool(value);
    } else if (stringFields.has(key)) {
      (overrides as Record<string, string>)[key] = value;
    } else {
      throw new BuildError(`Unknown config field: --${rawKey}`, {
        hint: `Known fields: profile, target, ${[...boolFields, ...stringFields].sort().join(", ")}`,
      });
    }
  }

  return { profile, overrides, ninjaTargets, ninjaArgs, execArgs, configureOnly, quiet, configFile };
}

function parseBool(v: string): boolean {
  const lower = v.toLowerCase();
  if (["on", "true", "yes", "1"].includes(lower)) return true;
  if (["off", "false", "no", "0"].includes(lower)) return false;
  throw new BuildError(`Invalid boolean value: ${v}`, { hint: "Use on/off, true/false, yes/no, or 1/0" });
}

const USAGE = `\
Usage: bun scripts/build.ts [options] [exec-args...]

View on GitHub (pinned to 8c5296ac45)

Solutions

1. Read the hint — it lists the valid fields; use exactly those names
2. Fix the typo (e.g. --profiled -> --profile)
3. For flags meant for the built binary, drop the `=` form so they route to execArgs
4. Check USAGE (run bun scripts/build.ts with no args) for the current option set

Example fix

# before
$ bun bd --asan=off --canary=true
BuildError: Unknown config field: --canary

# after — only real config fields; runtime flags go after the build args
$ bun bd --asan=off

const known = new Set(["profile", "target", "configFile" /*, ...boolFields, ...stringFields */]);
for (const arg of process.argv.slice(2)) {
  const m = /^--([^=]+)=/.exec(arg);
  if (m && !known.has(m[1])) {
    console.error(`unknown --${m[1]}; valid: ${[...known].sort().join(", ")}`);
    process.exit(2);
  }
}

const isKnownConfigKey = (k: string) =>
  k === "profile" || k === "target" || k === "configFile" || boolFields.has(k) || stringFields.has(k);

When it happens

Trigger: A typo like --canary=true for a field named differently; passing a bun-debug runtime flag with an `=` (runtime flags without `=` fall through to execArgs safely); using a field name removed or renamed in this version of build.ts.

Common situations: Flags remembered from an older checkout; CI scripts carrying stale option names; autocomplete or muscle-memory typos.

Related errors

• Cannot exec: build mode produced no executable
• --${rawKey} requires a value
• Invalid boolean value: ${v}
• Failed to load config file: ${path}
• Usage: ./${scriptPath} [ssh|create-image|publish-image] [opt

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