Common errors
Causes and fixes for frequent Bun error messages, grouped by the stage where they occur
| Error | Likely cause | Fix |
|---|
bun: command not found | ~/.bun/bin is not on PATH | Reopen the terminal; the installer's PATH hint only applies after the shell config reloads |
unzip is required to install Bun | unzip missing on Linux | sudo apt install unzip (or your distro's equivalent), then rerun the installer |
| Compatibility error right after installing on Windows | OS older than Windows 10 1809 | Upgrade Windows; there is no workaround |
| Error | Likely cause | Fix |
|---|
lockfile had changes, but lockfile is frozen | package.json and bun.lock are out of sync | Run bun install locally, review the diff, commit bun.lock together with the manifest |
bun audit reports a missing lockfile | No bun.lock in the repo | Run bun install first; audit reads the lockfile |
bun audit --production fails as an unknown flag | That spelling is unsupported | Use bun audit --prod; filtering at monorepo roots has a known defect |
Blocked postinstall in install logs | Dependency is not in the trust list | Inspect with bun pm untrusted; after review, grant minimally with bun pm trust <pkg> |
Cannot find package inside a workspace | Package added/moved without reinstalling | Run bun install at the repo root; confirm workspaces covers the directory |
--frozen-lockfile fails right after bun update | Lockfile write defect | Run bun install once more locally and commit (see known issues) |
| Error | Likely cause | Fix |
|---|
EADDRINUSE / port already in use | A stale process or port conflict | Pick a different PORT or stop the old process; check for stray --watch processes |
error: Script not found "xxx" | Wrong working directory or a typo | Confirm the package.json in the current directory; bare bun run lists available scripts |
| Stale or unexpected environment variables | Bun auto-loaded a local .env | Use --no-env-file in production so only platform-injected variables apply |
Bun.serve streaming responses cut off after ~10s | Default idleTimeout is 10 seconds | Raise idleTimeout after evaluation, or call server.timeout(req, 0) per request — keep an application-level total timeout |
| Error | Likely cause | Fix |
|---|
Cannot find module 'bun:test' or missing Bun global types | Bun types not installed/declared | bun add -d @types/bun; since TypeScript 6 also set "types": ["bun"] in tsconfig.json |
--isolate fails on dynamic import of top-level-await modules | Known regression in 1.3.14 | Run affected suites serially; track known issues |
Tests interfere with each other under --parallel | Shared ports, databases, or temp directories | Allocate per-worker resources via BUN_TEST_WORKER_ID, or keep that group serial |
- Run
bun --version, then rule out "version too old" against the version matrix.
- Confirm the working directory and the
package.json / bunfig.toml actually in effect.
- Build a minimal reproduction to separate project configuration from Bun runtime behavior.
- Check known issues and oven-sh/bun issues before upgrading or working around.
Bun Docs