DEV Community: 박준희

GitHub Actions vs. GCE Pull Poller: My Single VM Deployment Battle

박준희 — Wed, 03 Jun 2026 07:13:50 +0000

Running a full AI product, aicoreutility.com, on a single, modest VM is a constant exercise in resource management and engineering pragmatism. Most days, it's a quiet hum of activity. But every so often, a bug or a deployment hiccup reminds me of the fragility of this setup. One such incident, which recurred a few times, was the dreaded empty .next directory after a deployment.

The Symptom: A Ghost in the Machine

The symptom was always the same: after a deploy, the website would become inaccessible, returning a 500 error. Digging into the logs, the culprit was consistently an empty or corrupted .next directory. This directory is where Next.js outputs the built application, and without it, the server has nothing to serve.

This wasn't a random occurrence. It seemed to happen most often during automated deployments triggered by pushes to GitHub. My initial thought was that the build process itself was failing, perhaps due to resource constraints on the VM. I'd check the build logs, and sometimes they'd show errors, but other times, they'd appear to complete successfully, only for the .next directory to be missing or empty upon inspection.

The Wrong Turns: Chasing Shadows

My first few attempts to fix this involved tweaking the build process itself. I experimented with different build commands, ensuring all dependencies were correctly installed, and even tried increasing the VM's memory temporarily. I also looked at the deployment scripts, trying to add more robust error checking.

One of the key parts of my deployment strategy was an atomic swap. After a successful build, the new build artifacts (in a temporary directory like .next.new) would be swapped with the current production directory (.next). This ensures that if the new build fails, the old one remains untouched. However, in this scenario, it seemed like the swap was either not happening correctly, or the build itself was producing an empty output before the swap even occurred.

I also had a watchdog script running, but it was primarily focused on the PM2 process and basic server health checks. It wasn't sophisticated enough to detect an empty .next directory as a critical failure before it caused a full outage. The PM2 process would still be running, but it would be serving nothing.

The Root Cause: A Race Condition on a Single VM

The recurring nature of the problem, especially with automated pushes, pointed towards a timing or concurrency issue. The material I reviewed highlighted the core problem: my GitHub Actions workflow was executing the build and swap operations within an external SSH session or job. If this session timed out, or the connection was interrupted for any reason, the atomic swap could be left incomplete. The new build artifacts might end up in .next.new, but the swap to .next would fail, leaving the production directory empty or corrupted. The PM2 process, unaware of this underlying file system issue, would continue to run, leading to the 500 errors.

Essentially, the external nature of the GitHub Actions build and deploy process, combined with the potential for transient network issues or session timeouts on a single VM, created a race condition. The build could succeed, but the critical final step of making it live could fail silently, leaving the application in a broken state.

This was particularly insidious because the build logs might not always show a clear error. The process might just... stop. And the watchdog, not designed to check the integrity of the .next directory itself, wouldn't catch it until the next request came in.

The Fix: Embracing the Simpler Path

The solution, as documented in my build logs, was to simplify the deployment process and eliminate the external dependency that was causing the race condition. I decided to move away from the GitHub Actions-driven build and swap and instead rely solely on a Google Compute Engine (GCE) pull poller.

Here's how the new system works:

GitHub Actions Disabled for Auto-Deploy: The deploy.yml workflow was modified to only allow manual triggers (workflow_dispatch). Automatic deployments via on.push were commented out, effectively disabling them for routine use.
GCE Pull Poller: A systemd timer (riel-autodeploy.timer) is set to run every 90 seconds. This timer triggers a script (auto_deploy_poll.sh).
Server-Side Build and Deploy: The auto_deploy_poll.sh script, in turn, calls redeploy.sh auto. Crucially, this script runs entirely on the server itself. It checks if a redeploy is necessary (e.g., if frontend, chat, or backend code has changed). If a redeploy is needed, it performs the build, smoke tests, and atomic swap all within the server's environment.
Flock and Gates: The redeploy.sh script now uses flock to prevent multiple instances from running concurrently and includes more robust checks. It ensures that the build is complete and the resulting .next directory is not empty and has a valid BUILD_ID before proceeding with the swap. It also ignores temporary connection issues during PM2 reloads, only rolling back on genuine failures (4xx, 5xx, chunk 404s).

This approach eliminates the external session dependency. The build and swap happen in a controlled environment on the VM, making it far less susceptible to network interruptions or timeouts that plagued the GitHub Actions method. The watchdog script was also updated to check for the integrity of the .next directory (non-empty, valid BUILD_ID, sufficient chunks) rather than just relying on PM2's status.

The Lesson: Simplicity is Robustness

This incident reinforced a core principle of solo development on limited infrastructure: simplicity often breeds robustness. While GitHub Actions is a powerful tool, its complexity introduced a failure mode that was difficult to debug on a single VM. By reverting to a simpler, server-side pull poller, I've created a deployment process that is more resilient to the inherent instabilities of a shared environment. The occasional need to manually trigger a deploy via GitHub Actions is a small price to pay for the increased stability and reduced downtime.

...building aicoreutility.com in the open... aicoreutility.com

Next.js 14: 'Could not find the module in the React Client Manifest' — the real cause nobody tells you

박준희 — Wed, 03 Jun 2026 07:13:50 +0000

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.

The setup that caused it

My deploy script did something that looks perfectly reasonable:

Build the app in a scratch directory: /tmp/riel_agent_build
Keep the old, running .next untouched during the build (zero downtime)
When the build succeeds, swap just the new .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.

The real cause: RSC bakes an absolute path into the client manifest

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 fix: build in place, into a sibling output dir

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

# build into a NEW folder, leaving the live .next serving traffic
rm -rf node_modules/.cache           # drop any path-polluted cache
NEXT_DIST_DIR=.next.new npx next build

# sanity-check the output before swapping (see guard below)

# atomic swap
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:

Clear node_modules/.cache. Webpack/Next caches can carry the old build path forward and reintroduce the mismatch. A poisoned cache will happily rebuild the wrong absolute paths.
The old .next stays live during the build. Because you're building into .next.new, the running app never loses its .next. The only moment of change is the mv, which is atomic on the same filesystem.

The guard rail I added so it can never ship silently again

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.

# after building into .next.new, before swapping
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 lesson

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.