Keep an Error Journal When You Are Stuck. A Build Next Stack field guide for learners shipping small projects.
When an error belongs in the journal
Log an entry when the same error costs you more than twenty minutes, when you fix it but cannot explain why, or when you swear you saw it last month. Skip one-off typos and obvious missing imports unless they hide a pattern—like always forgetting a dev dependency after clone.
The journal is not a ticket system for your employer. It is personal retrieval for future-you at 11pm when search results contradict each other. One line in the journal beats twenty minutes re-googling.
Keep the journal beside the project—errors.md in the repo root, or a dated note linked from the repo README. Remote journal in a personal vault works if every entry ends with the repo name and branch.
Omar kept errors only in browser history and lost an afternoon every month rediscovering the same CORS preflight mistake. Moving to errors.md did not make him error-free; it made repeats searchable with #network in under ten seconds.
Commit the journal file with the project when it contains no secrets. If entries include keys or tokens, keep a private copy and commit a sanitized template instead.
One line per entry format
Each entry is one scannable block:
- Date + symptom: 2026-07-06 — API returns 403 only in production build
- Cause (after fix): env var missing in hosting panel, not in .env.example
- Fix: add KEY to host; document in README deploy section
- Tag: #deploy #env
Write the cause after you fix it, not before. Premature cause lines encode guesses that mislead later. If cause stays unknown, write unknown — masked by restart and schedule a reproduction experiment.
Never paste stack traces longer than five lines; link to commit or gist instead. Future-you needs the story, not four hundred lines of minified vendor code.
Add an optional Search phrase line—the exact error string you typed into Google. When the fix works, you learn which phrasing finds signal versus SEO spam next time.
Tag errors by layer not mood
Tags describe where the failure lived: #network, #auth, #build, #database, #ui, #tooling. Avoid tags like frustrating or weird—they do not sort.
When three entries share a tag in one month, that layer deserves a cheat sheet note: common commands, checklists, links to official docs. The journal pointed at the layer; the cheat sheet prevents repeat tax.
Limit yourself to eight tags total. Tag sprawl is taxonomy procrastination wearing a learning costume.
Weekly pattern scan in ten minutes
Every Sunday—or bundled into Friday learning review—scan the last seven entries. Ask:
- Did any symptom repeat with a different fix? Consolidate entries; conflicting fixes mean you never understood the cause.
- Did one tag dominate? Schedule a focused read of official docs for that layer—not another random tutorial.
- Any entry still says unknown? Pick one for a reproduction timebox next week.
Ten minutes is enough. Pattern scan is not root-cause analysis for every line; it is triage so the journal stays trustworthy.
Pair journal entries with reproduction steps
When an error is worth logging, it is worth reproducing once on purpose. Add a Repro line:
Repro: clean clone → npm ci → npm run build → open /settings on Safari — 403 appears.
Repro steps turn lucky fixes into transferable skill. They also expose when the bug was environmental voodoo—works after restart with no repro deserves an honest journal line so you do not pretend mastery.
Store repro commands in copy-paste blocks. Shell history is not documentation; history rolls off and machines change.
Retired errors archive
Move entries older than ninety days to an archive section at the bottom of the file. Keep tags intact. Archive is for search, not daily reading.
Once a quarter, delete archived entries you never searched. If you never searched, the write-up was too vague or the problem never returned—both mean the entry failed its job.
Celebrate retired tags: if #webpack has zero entries in sixty days, your build setup matured. That is learning progress measurable without a certificate.
Archived entries that saved you time deserve a one-line saved ~40 min on 8/14 note when you search them. Positive reinforcement keeps the journal open during stress.
Field example: production 403 that was not auth
Omar’s journal entry from a real deploy week:
- Symptom: API 403 only after
npm run build, fine in dev - Cause: hosting env missing
API_KEY; dev read.env.local - Fix: set host var; add key name to README deploy checklist
- Repro: build locally with empty env — same 403
- Tag: #deploy #env
Two weeks later, a staging deploy failed with 403. Omar searched #deploy, ran repro in four minutes, fixed host panel—not auth middleware he almost rewrote. That is the journal paying rent.
He added a deploy checklist bullet: verify env vars before promoting build. Journals spark checklists when tags repeat; checklists prevent entries from multiplying without learning.
If you maintain multiple repos, prefix entries with repo slug so one search across vault files still sorts clearly.
Omar also logs Time lost in minutes when known—twenty here, ninety there. Monthly sums show which layers tax him most, turning journal into lightweight telemetry without a spreadsheet obsession.
Log the next error before you fix it
On your next stall, open the journal first and write the symptom line while the console is still open. Fix second. Cause line third. The sixty seconds of logging beats the hour you will spend re-fighting the same ghost next month.
Error journals compound quietly. They do not make you a senior engineer overnight—they make stuck nights shorter and less lonely.
Create errors.md tonight with three blank entry templates and one real line from the last bug you remember. Future searches need something to find.
When an entry saves you time later, add a saved time note in the margin. Positive proof keeps the habit alive when debugging feels thankless.
Review the journal during Friday learning review—sixty seconds scanning new tags is enough to spot layers that need a cheat sheet before next week.