I run a small AI product on a single cheap VM, deploying it myself. One morning the homepage started throwing 500s — not always, just sometimes. The admin pages were fine. The CSS was fine. Only some routes died, and only in production.
The error in the PM2 logs was this:
Error: Could not find the module
"/tmp/riel_agent_build/src/app/page.tsx#default"
in the React Client Manifest.
This is probably a bug in the React Server Components bundler.
"Probably a bug in the bundler." It wasn't. It was me. If you're self-hosting Next.js 14 (App Router / RSC) and seeing this, here's what's actually happening — and it took me far too long to see it.
My deploy script did something that looks perfectly reasonable:
/tmp/riel_agent_build
.next
untouched during the build (zero downtime).next
into the live app directory /home/me/app/riel_agent
Build somewhere safe, then move only the output. Classic atomic deploy. The problem is that one of those build artifacts is not relocatable.
In the Next.js App Router, React Server Components need a client manifest — a map that tells the server which client module to hydrate for each "use client"
boundary. In Next.js 14, the keys in that manifest are written using the absolute path of the directory the build ran in (the build CWD).
So when I built in /tmp/riel_agent_build
, the manifest was full of keys like:
/tmp/riel_agent_build/src/app/page.tsx#default
Then I moved .next
to /home/me/app/riel_agent
and started the server from there. At runtime, Next resolves modules relative to the real CWD — /home/me/app/riel_agent/...
— but the manifest is still pointing at /tmp/riel_agent_build/...
. The two no longer match. For any route that crosses a server→client boundary, the lookup fails:
Could not find the module
/tmp/riel_agent_build/...
in the React Client Manifest.
Why "only sometimes"? Because routes with no client component (or that were statically pre-rendered) don't hit the manifest at all. Pure-static pages render fine; the moment a route needs to hydrate a client boundary at request time, it 500s. That's why my admin pages looked healthy while the homepage flickered between working and broken.
The tell is right there in the error string: it's an absolute path that is not where your app actually lives. If you ever see /home/runner/...
(GitHub Actions) or /tmp/...
in this error, you have the exact same disease. (I had previously hit the /home/runner
version of this and "fixed" it by moving the build to /tmp
— i.e. I moved the bug, not removed it.)
The relocation was the whole problem, so the fix is to never relocate. Build with the real app directory as the CWD, and only redirect the output folder, not the working directory.
Next.js already supports this. next.config.js
reads the dist dir from an env var:
// next.config.js
module.exports = {
distDir: process.env.NEXT_DIST_DIR || ".next",
// ...
};
So the deploy becomes:
cd /home/me/app/riel_agent # real CWD — same as runtime
rm -rf node_modules/.cache # drop any path-polluted cache
NEXT_DIST_DIR=.next.new npx next build
mv .next .next.previous
mv .next.new .next
pm2 reload riel_agent
Now the manifest keys are written as /home/me/app/riel_agent/...
— which is exactly where the server runs from. The paths match, the 500s stop, and I still get a zero-downtime swap because the old .next
keeps serving until the very last mv
.
Two details that matter:
node_modules/.cache
..next
stays live during the build..next.new
, the running app never loses its .next
. The only moment of change is the mv
, which is atomic on the same filesystem.A deploy that produces a technically successful build but a broken manifest is the worst kind — it passes "did the build exit 0?" and still takes the site down. So I added a dumb, deterministic check before the swap: grep the new server output for any path that isn't the real app directory.
if grep -rqE '/tmp/|/home/runner/' .next.new/server; then
echo "FATAL: foreign build path leaked into manifest — refusing to swap"
exit 1
fi
If any /tmp/...
or /home/runner/...
string made it into the server bundle, the deploy refuses to swap and the previous build keeps running. No LLM judgment, no heuristics — just a string match for "this build was made somewhere it shouldn't have been."
The interesting part isn't the Next.js trivia. It's that a build artifact had a hidden dependency on its own location, and my "safe" deploy strategy quietly violated it. The error blamed the bundler; the real bug was an assumption in my pipeline — "build output is relocatable" — that happened to be false for exactly one file.
When a green build still breaks production, stop trusting "it compiled" and look for the thing that's environment-specific: an absolute path, a baked-in env var, a cache. The fix is rarely more code. It's removing the assumption.
I'm building aicoreutility.com in the open — a full AI product run by one person on one small VM. Most of what I write here is the unglamorous infrastructure that broke first. This one cost me a morning of 500s.