Troubleshooting
The errors you're most likely to hit when you first build a program with bun compile, and the fix for each
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#
const port: number = "3000";
console.log(port);bun compile ./port.tserror: TS2322: Type 'string' is not assignable to type 'number'.
at /path/to/port.ts:1:7bun 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.
| Message | What to do |
|---|---|
TS100014: this assignment always throws | Don't replace built-ins |
TS100053: Macros are disabled | bun compile doesn't run macros. Pass --no-aot |
TS100073: This comment silences nothing | Delete the bun-ignore comment, or fix the code it names |
TS100308: The package "x" has 2 type errors | Your 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 constant | The build may not find the file. Pass it as another entry point, then silence the warning |
TS100064: this call loads a module | Import the node: or bun: module by name somewhere in your program |
TS100080, TS100091, TS100092, TS100093 | Loader hooks and require.cache don't reach compiled modules |
bun compile can't cross-compile | Build on that platform, or pass --no-aot |
--aot does not apply to a package.json script | Put --aot on the bun command inside the script |
this build of Bun doesn't support --trim | Use 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,
TS100000toTS100999. It never silences a type error, an error that stops the build, or a warning that isn't about a line, such asTS100308. - 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,.jsxand.tsxfiles, and in dependencies. Between JSX elements, write{/* bun-ignore TS100064 */}. --explainstill lists each warning that a comment silenced.
Errors when the program runs#
| Message | What to do |
|---|---|
... because built-in objects are read-only | Don't replace built-ins |
Cannot find module | The build didn't embed the file. Pass it as another entry point. |
Cannot load ...: it isn't in this executable | Pass the file as another entry point. Import a node: or bun: module by name |
... was not compiled into this executable | Use 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 executable | The 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.
- Your hot code is untyped.
bun compile --explainlists the code that compiled to a slow path, worst first, with a fix for each. - 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.
- A library generates code at run time, and Bun interprets it.
- The program runs WebAssembly that it downloads or assembles at run time.
- 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.