Troubleshooting

The errors you're most likely to hit when you first build a program with bun compile, and the fix for each

Ahead-of-time compilation is experimental.

Find your message in one of the tables. They show the part of each message that doesn't change.

The build stops at a type error#

port.ts
const port: number = "3000";
console.log(port);
terminal
bun compile ./port.ts
error: TS2322: Type 'string' is not assignable to type 'number'.
    at /path/to/port.ts:1:7

bun run never checks your types, so a project can carry type errors for years. bun compile relies on them.

bun check --aot ./port.ts lists every error the build would report, and builds nothing. Fix them, or put // @ts-expect-error above a line that you can't fix yet. "noCheck": true in tsconfig.json turns all of them off, as it does for tsc.

The errors are TypeScript 7's, whichever version of typescript you have installed. Coming from TypeScript 5 lists what changed.

The build reports type errors in your own files only. If a package has type errors in the TypeScript that gets compiled, bun check --aot ./port.ts says so in one warning, and bun check --aot --all ./port.ts lists them.

Other messages from the build#

An error stops the build. After a warn you still get an executable, but the line it points at may fail when it runs.

MessageWhat to do
TS100014: this assignment always throwsDon't replace built-ins
TS100053: Macros are disabledbun compile doesn't run macros. Pass --no-aot
TS100073: This comment silences nothingDelete the bun-ignore comment, or fix the code it names
TS100308: The package "x" has 2 type errorsYour build doesn't stop for them. bun check --aot --all lists them, so you can report them to the package
TS100064: this import path isn't a constantThe build may not find the file. Pass it as another entry point, then silence the warning
TS100064: this call loads a moduleImport the node: or bun: module by name somewhere in your program
TS100080, TS100091, TS100092, TS100093Loader hooks and require.cache don't reach compiled modules
bun compile can't cross-compileBuild on that platform, or pass --no-aot
--aot does not apply to a package.json scriptPut --aot on the bun command inside the script
this build of Bun doesn't support --trimUse a release of Bun, not one you built

Silence a warning#

If you've checked a line and its warning doesn't apply, write a bun-ignore comment with the warning's code. Put it on the line above, or at the end of the line:

// bun-ignore TS100064 every plugin is an entry point
const plugin = require(pluginPath);

const found = Bun.resolveSync("./plugin.js", import.meta.dir); // bun-ignore TS100099 only under bun run
  • Any text after the codes is yours, so say why.
  • To silence several warnings on one line, list their codes: // bun-ignore TS100064, TS100099. No form silences every warning.
  • It silences the compiler's own warnings and notes, TS100000 to TS100999. It never silences a type error, an error that stops the build, or a warning that isn't about a line, such as TS100308.
  • A comment that silences nothing gets a warning of its own, TS100073, so stale comments don't pile up. A comment in code that this build leaves out, such as a function it never calls, isn't stale: another build of the same file may need it. A build that stops at an error calls no comment stale.
  • It works in .js, .ts, .jsx and .tsx files, and in dependencies. Between JSX elements, write {/* bun-ignore TS100064 */}.
  • --explain still lists each warning that a comment silenced.

Errors when the program runs#

MessageWhat to do
... because built-in objects are read-onlyDon't replace built-ins
Cannot find moduleThe build didn't embed the file. Pass it as another entry point.
Cannot load ...: it isn't in this executablePass the file as another entry point. Import a node: or bun: module by name
... was not compiled into this executableUse that API once in your own code
EvalError: ... the compiler couldn't tell ...Call eval or new Function directly
... can't be used with this executableThe option needs code that wasn't compiled in. The message names the flag to rebuild with
Cannot compile C code ... (PR_SET_MDWE)Compile the C file first, then dlopen()

Built with --no-compile-function-source, a message that quotes your code says less, so your error tracker may show new groups.

The executable is slower than bun run#

Look for these causes, in this order.

  1. Your hot code is untyped. bun compile --explain lists the code that compiled to a slow path, worst first, with a fix for each.
  2. A value doesn't match its declared type in hot code. Nothing is printed, because nothing goes wrong. Testing and debugging shows how to find it.
  3. A library generates code at run time, and Bun interprets it.
  4. The program runs WebAssembly that it downloads or assembles at run time.
  5. Code is loaded from disk, with --aot-allow-code-from-disk. Bun interprets that too.

The executable is too large#

--trim removes the Bun and Node.js APIs that your code never calls. If that changes little, something in your program could reach any API, usually eval or a dynamic require(). --explain=trim says what. --no-compile-function-source leaves out the source text of your functions.

Something else#

If a program passes bun check --aot and still behaves differently from bun run in a way that Compatibility doesn't describe, open an issue with the smallest program that shows it.