Debugging Skill

Hard-won lessons from real failures. Follow this before spending time on dead ends.

Rule 1: Build Locally First

Before deploying to any remote environment (Dokploy, CI, etc.), always verify the build locally:

bun run build / npm run build — catches TypeScript errors, unused imports, missing modules
docker build . — catches Dockerfile issues, dependency problems
Run the test suite if one exists

Why: A TypeScript strict mode error (TS6133: unused import) caused 7 consecutive Dokploy deploy failures. A 2-second local build would have caught it instantly. Instead, 30 minutes were wasted trying to read remote logs that weren't accessible.

Learned: 2026-01-29 — hammer-queue deploy failures

Rule 2: Reproduce Before Escalating

When a remote deploy/service fails:

Build locally first (Rule 1)
Run locally if possible (bun run dev, docker compose up)
Check the runtime — does the app start? Does db:push/migration work?
Only after local reproduction fails should you investigate server-side issues

Why: The serial column type worked in schema definition but broke drizzle-kit push on an existing table with data. Building locally passed, but running locally would have caught the db migration failure.

Learned: 2026-01-29 — serial column broke db:push on existing table

Rule 3: Check the Obvious First

Before diving into API spelunking or log hunting:

Compiler errors? (tsc, build output)
Missing imports or unused imports? (strict mode)
Schema changes compatible with existing data?
Environment variables set correctly?
Ports/URLs correct?

Rule 4: When Blind to Logs, Create Your Own

If you can't access remote logs (no API endpoint, no SSH, no UI access):

Don't spend more than 5 minutes hunting for log endpoints
Do reproduce the issue locally where you CAN see logs
Do add health check endpoints that report startup errors
Do add structured error logging that surfaces in API responses

Rule 5: Time-Box Dead Ends

If an approach isn't working after 5-10 minutes, switch strategies:

Can't read Dokploy logs via API? → Build locally instead
Can't SSH to server? → Use available APIs differently
API returning opaque errors? → Test the component in isolation

Rule 6: Schema Migration Safety

When modifying database schemas on existing tables:

serial columns can't be safely added to existing tables via drizzle-kit push — use integer with app-level sequencing instead
Always consider: "What happens to existing rows?"
Test migrations against a database with real data, not just empty tables
Prefer nullable columns with backfill logic over NOT NULL additions

Deployment Checklist

Before every deploy:

[ ] Local build passes (frontend + backend)
[ ] TypeScript strict mode clean (no unused imports/vars)
[ ] Schema changes tested against existing data
[ ] Environment variables verified
[ ] Push to git
[ ] Deploy
[ ] Verify health endpoint after deploy
[ ] Verify API functionality

This skill is a living document. Update it every time a new debugging lesson is learned.

3.1 KiB Raw Permalink Blame History