The Day `package.json` Disappeared and My Deployment Broke — A Next.js Sibling Build Recovery Story

Symptoms

My GitHub Actions deployment failed twice in a row. The error messages were different each time:

Error: Cannot find module 'next/dist/compiled/browserslist'
...
Error: Cannot find module 'styled-jsx/package.json'

The weird part: the site was working perfectly. Main page, blog, chat – all returning 200. Only new builds were breaking. It was like a ghost state where the runtime was alive but the build was dead.

Initial Misdiagnosis — Mistaken for a node_modules Issue

Since it said "module not found," I assumed my dependencies were broken and ran npm ci. But then:

npm error code ENOENT
npm error syscall open
npm error path /home/user/app/package.json
npm error errno -2
npm error enoent Could not read package.json

The package.json itself was missing. It wasn't node_modules that was the problem, but the manifest file that had vanished.

The Real Cause — File Deleted from the Working Tree

Checking the git status, I saw:

$ git status
On branch main
Changes not staged for commit:
  deleted:    riel_agent/package.json

The file was tracked by git, but the actual file in my working tree had been deleted. (I probably accidentally deleted it while manually cleaning up build artifacts previously.)

Why was the site still running? Because PM2 was using the already built .next/ artifacts. The runtime doesn't need package.json to function. However, a new deployment (which involved a `cp -al` sibling copy and then `npm install`) failed because without package.json, it couldn't build the dependency tree, leading to stale node_modules and missing modules.

The Fix — One Line of Git

# Restore from HEAD since it's a tracked file
git checkout HEAD -- riel_agent/package.json

# Clean up the broken sibling build directory
rm -rf /tmp/riel_agent_build

# Ensure integrity with a clean reinstall
npm ci --prefer-offline --no-audit --no-fund

After restoring, I checked:

$ ls node_modules/styled-jsx/package.json
node_modules/styled-jsx/package.json   ✓
$ ls node_modules/next/dist/compiled/browserslist/
LICENSE  index.js  package.json   ✓

Lessons Learned

1. "Module not found" errors might not be dependency issues, but manifest problems. The real reason npm couldn't find browserslist was the absence of package.json, which prevented it from building the dependency tree at all. I should have looked one level higher (package.json) instead of just at the surface error (browserslist).
2. Runtime healthy ≠ Build healthy. PM2/standalone artifacts can run even if some source files are broken. The trap is thinking "the site is up, so it's fine." The deployment pipeline relies on the integrity of your source.
3. `git checkout` is your best recovery tool. If a tracked file disappears, `git checkout HEAD -- <file>` is all it takes. No need to hunt for backups.
4. Never manually clean build directories. This was the root cause of this incident. Automate cleanup with scripts and retention policies, and never touch the source directories.