---
title: "Troubleshooting"
description: "Common errors and their fixes when building or running a next-bun-compile binary."
---

> Documentation Index
> Fetch the complete documentation index at: https://ramonmalcolm10.github.io/next-bun-compile/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

## `Cannot find module 'next-bun-compile'`

Next resolves `adapterPath` from its own package location. In
monorepos or linked workspaces, resolve from the app dir instead:

```ts
import { createRequire } from "node:module";
const req = createRequire(process.cwd() + "/");

const nextConfig: NextConfig = {
  adapterPath: req.resolve("next-bun-compile"),
};
```

## `adapter outputs not found for this build`

The compile pipeline ran without the adapter (e.g. against a stale
`.next`). Build through the adapter — `adapterPath` in `next.config`
or `NEXT_ADAPTER_PATH=next-bun-compile next build` — and make
sure nothing removed `.next/nbc-adapter-outputs.json` between the
build and the compile.

## `Failed to load external module pino-...: Cannot find package`

Some packages (`pino`, `pino-pretty`) use dynamic `require()` calls
internally that Turbopack can't statically resolve. They get
externalized with a mangled name that doesn't exist in your
node_modules.

**Fix.** Force them through the bundler with `transpilePackages`:

```ts
const nextConfig: NextConfig = {
  adapterPath: "next-bun-compile",
  transpilePackages: ["pino", "pino-pretty"],
};
```

See [transpilePackages guide](/next-bun-compile/next-bun-compile/guides/transpile-packages/).

## `Could not load the "sharp" module using the linux-x64 runtime`

Sharp loaded but couldn't dlopen its native binding. This is sharp's
own error after exhausting its load paths — it's a runtime
environment issue, not a next-bun-compile issue.

**Fix.** Use a runner image with the libs sharp's prebuilt expects:

- `gcr.io/distroless/cc-debian12:nonroot` — has `libstdc++` (the
  `cc` variant). The plain `base` variant lacks `libstdc++` and
  sharp won't load.
- For text rendering (watermarks): also need fontconfig + a font
  face. Full recipe in
  [Distroless + sharp](/next-bun-compile/next-bun-compile/recipes/distroless-sharp/).

## `Fontconfig error: Cannot load default config file`

libvips (sharp's image engine) needs fontconfig + actual font files
to render text. Distroless images don't include either.

**Fix.** Copy them from the builder. See the recipe section in
[Distroless + sharp](/next-bun-compile/next-bun-compile/recipes/distroless-sharp/).

## Binary boots, then 500 on first request

Often a missing env var your app needs at runtime — check what's
required and ensure the deploy sets them. Common cases:

- `DATABASE_URL` or similar (no value → driver crashes on first use)
- Stripe / OAuth secrets your code expects

**Diagnostic.** Set `NEXT_BUN_COMPILE_DEBUG=1` and re-run; the log
will show every resolver-hook decision so you can rule out a
resolution failure.

## "Cannot find package 'X-abc123...'" with a 16-char hex suffix

A turbopack-mangled alias the resolver couldn't redirect. The
build-time validator should have warned about this — check the
build log for:

```
next-bun-compile: ⚠ N of M turbopack alias reference(s) won't resolve at runtime:
  ✗ X-abc123def456... → X
```

**Fix.** The canonical package isn't in the assembled output tree. Either:

- Add it as a dependency
- Or add it to `transpilePackages` so it's bundled into the chunks
  instead of externalized

## Binary can't write next to itself (read-only filesystem)

The binary extracts runtime files beside itself by default. On
read-only root filesystems (Kubernetes `readOnlyRootFilesystem`,
read-only containers), point extraction at writable tmpfs:

```bash
NBC_RUNTIME_DIR=/tmp/app ./dist/app
```

## Want to see what's happening at runtime?

```bash
NEXT_BUN_COMPILE_DEBUG=1 ./dist/app
```

Logs every resolver-hook decision with parent-file context. See
[Debug mode](/next-bun-compile/next-bun-compile/guides/debug-mode/) for output
examples and how to read them.

## Still stuck?

Open an issue with:

1. The error output
2. `NEXT_BUN_COMPILE_DEBUG=1` log of the failing request (if it
   happens at runtime)
3. Your `next.config.ts`
4. A list of native deps in your `package.json`

[Open an issue →](https://github.com/ramonmalcolm10/next-bun-compile/issues/new)

Source: https://ramonmalcolm10.github.io/next-bun-compile/troubleshooting/index.mdx