Database and local startup

npm run migrate fails with Acquire connection error

Acquire connection error: AggregateError
    at internalConnectMultiple (node:net:1430:18)

npm run dev in backend/ still starts, then its email worker logs:

ERROR [EmailProcessor] Email queue processing failed
...
Error: connect ECONNREFUSED 127.0.0.1:5433

Why: nothing is listening on the database port. The dev Postgres runs in Docker and is published on port 5433, which DATABASE_URL in backend/.env points at.

Fix: from the repository root, start it and run the command again:

docker compose up -d --wait postgres maildev

If 5433 is taken on your machine, see Start the database and the app.

The backend answers 500 and logs relation "..." does not exist

ERROR [ExceptionsHandler] error: select * from "blog_posts" ... - relation "blog_posts" does not exist

Why: the database is up but has no tables. Migrations have not run against it.

Fix: npm run migrate in backend/. Run it again whenever a new file appears in backend/migrations/.

Related

• Troubleshooting - all entries
• Verify failures