Debugging a Monorepo: When Everything Works, But Nothing Does

I inherited a Notes Server project—a sprawling monorepo with five separate packages, each with its own opinions about how the world should run. The task seemed simple: verify dependencies and confirm the project actually starts. Famous last words.

The structure looked clean on paper: packages/server (Node backend), packages/web-client (Vue.js + Vite), packages/embeddings-service, packages/cli-client, and packages/telegram-bot-client, all glued together with npm workspaces. I ran npm install at the root. Standard. Expected. Boring.

Then I tried to start the server. Port 3000 came alive. The web client? Port 5173 with Vite was already spinning. Both processes running, both seemingly healthy. I thought I’d won.

I didn’t.

When I hit http://localhost:3000/api/notes, the server responded with 404. Not a server crash—worse. A “Not Found” message, polite and completely unhelpful. The API routes should have been there. I’d seen them in notes-routes.ts. They were registered. They were mounted under /api/. So why were they vanishing?

I started digging. The Express app in index.ts was created via createApp(), which added all the API routes first. Then more middleware was layered on top. The static file serving came after. The route order looked correct—APIs should match before static files. But somewhere, something was intercepting requests.

Then it hit me: there was already a process running on port 3000 from a previous session. I’d spun up a new server, but the old one was still there, serving stale responses. A classic monorepo trap—multiple packages, multiple entry points, easy to lose track of what’s actually running.

After killing the orphaned process and restarting fresh, the routes appeared. The API responded. But the real lesson was humbling: in a monorepo, you’re fighting complexity at every step. Vite was set up to proxy API requests to port 3000, Vue was configured to talk to the right backend, everything should work. And it did—until it didn’t, because some invisible process was shadowing the truth.

The joke? A byte walks into a bar looking miserable. The bartender asks, “What’s wrong?” The byte replies, “Parity error.” “Ah, I thought you looked a bit off.” 😄 Turns out my server had the same problem—just needed to remove the duplicated state.