Runbook — MongoDB down / connection refused

Symptoms

• npm run dev boots, but any page that reads data shows a 500 or hangs.
• Server console: MongooseServerSelectionError: connect ECONNREFUSED 127.0.0.1:27017 or similar.
• Login fails; signup fails.

Diagnose

# Is anything listening on 27017?
lsof -i :27017

# Is the homebrew service running?
brew services list | grep mongodb

# Or check the forked daemon's log
tail -50 /tmp/mongodb/mongod.log

Fix

Pick the path that matches how Mongo was installed locally:

# Homebrew (most common on this machine)
brew services start mongodb-community

# Manual forked daemon
mongod --dbpath /tmp/mongodb/data --fork --logpath /tmp/mongodb/mongod.log

# Docker
docker run -d -p 27017:27017 --name pf-mongo mongo
# or: docker start pf-mongo

Verify connection:

mongosh "mongodb://localhost:27017/personal-finance" --eval "db.runCommand({ ping: 1 })"

If data dir is missing or corrupt

mkdir -p /tmp/mongodb/data
# Then start as above. Empty DB — you'll need to re-signup or restore from backup.
npm run backup:export  # exports current data when the DB IS up

Env check

MONGODB_URI in .env.local should match where Mongo is actually listening. Default is mongodb://localhost:27017/personal-finance.

Related

• App AGENTS.md › Starting services
• [[Projects/personal-finance-notion/runbooks/runbook-pwa-outbox-stuck|runbook-pwa-outbox-stuck]] — outbox can mask Mongo outages on the client side