Debugging¶

A practical guide to diagnosing problems while developing on dichit-backend.

Fastest routes to information¶

Start with logs. All request/error logs carry a correlation/request id (reqId). Find the failing request's id, then grep for it.
Reproduce with the debug profiles below.
Check queues — background work runs in BullMQ; failures surface in Bull Board (/admin/queues) and Sentry, not the HTTP response.
Check Sentry for captured exceptions and performance traces.
Check PostgreSQL/Redis state directly (Prisma Studio, psql, redis-cli).

Log profiles¶

The LOG_* env vars (see environment-variables.md) control verbosity. Ready-made profiles:

pnpm start:local:debug              # LOG_LEVEL=debug, pretty logs, response bodies
pnpm start:local:debug:prisma       # + Prisma query logging
pnpm start:local:debug:all          # everything

Flag	Effect
`LOG_LEVEL=debug`	pino debug level
`LOG_PRETTY=true`	human-readable pino-pretty output
`LOG_RESPONSE_BODY=true`	log response bodies (do not enable in prod)
`LOG_PRISMA_QUERIES=true`	log every Prisma query
`LOG_PRISMA_QUERY_PARAMS=true`	include bound params
`LOG_PRISMA_SLOW_QUERY_MS=0`	log every query as slow (or set a real threshold)

Common issues¶

Port already in use / server won't bind¶

lsof -i :3500
kill -9 <pid>          # or: pkill -f 'tsx watch'

Prisma client is stale after schema edits¶

pnpm prisma:generate

tsx watch may not pick up the generated client; re-run generation after editing schema.prisma.

Migration drift / `migrate dev` wants to reset¶

pnpm migrate:local:status        # see state
pnpm migrate:local:reset         # wipe local DB and re-apply migrations + seed (destructive!)

Never reset shared dev/staging databases without coordination — see database/migrations.md.

Functional tests fail on DB/Redis¶

Ensure test containers are up:

pnpm docker:test:up
pnpm test:functional
pnpm docker:test:down

Weird values / BigInt in JSON¶

The server serializes BigInt to strings automatically (serializerOpts.bigint), so IDs like 25000 in DB fields may appear as "25000". That is expected.

WebSocket connection drops¶

Check the token: handshake requires a valid access JWT (see api/websocket/authentication.md).
Check heartbeat/idle timeouts (see api/websocket/connection.md).
Check Redis pub/sub health if events aren't delivered across instances (see api/websocket/rooms.md).

Profiling & performance¶

benchmarks/ + pnpm test:coverage with @codspeed/vitest-plugin for benchmarked unit tests.
Sentry performance traces (see infrastructure/monitoring.md).
Slow-query log: LOG_PRISMA_SLOW_QUERY_MS=200 to catch N+1 hotspots (see database/optimization.md).