From 72643154555730a9a32aae6e641e1b42eefeaff0 Mon Sep 17 00:00:00 2001 From: Mao Nakamoto <41178744+maonakamoto@users.noreply.github.com> Date: Tue, 1 Sep 2026 02:00:20 +0200 Subject: [PATCH] docs: a local build needs SESSION_SECRET, and the failure lies about why MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CLAUDE.md told you to run `next build` before declaring UI work done and never said how. A bare `npm run build` on this laptop dies with Failed to collect configuration for /api/auth/demo and that route queries `prisma.user`, so the obvious reading is "no `aoz_wohnen` database here, builds are impossible on this machine". Wrong — and believed twice on 2026-09-01, once confidently enough to be reported to George as an environment limitation. The real `[cause]`, further down the same log, is a missing SESSION_SECRET. With it set the build is exit 0, 56 static pages. Records the working command and the two traps stacked underneath it: piping the build hands you tail's exit status so a failure reports success, and an error naming a database-touching route is not evidence about the database. The cost of the wrong belief was skipping the one gate `npm run verify` explicitly does not cover. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01Cd183M6472xBgTKWA2is6h --- CLAUDE.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index c6a70501..d92f5a17 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -447,6 +447,27 @@ an import passes lint, typecheck and Jest, and fails only at build. Run a build before declaring UI work done; `src/lib/__tests__/use-client-directive.test.ts` guards that specific class. +**Building locally needs one env var, and without it the failure lies about +its cause.** A bare `npm run build` dies with `Failed to collect configuration +for /api/auth/demo` — a route that queries `prisma.user`, so the obvious +reading is "this laptop has no `aoz_wohnen` database, builds are impossible +here". That reading is wrong, and it was believed twice on 2026-09-01 before +anyone read far enough down the log to the real `[cause]`: +`SESSION_SECRET environment variable must be set in production`. + +```bash +SESSION_SECRET=local-build-only npm run build # exit 0, 56 static pages +``` + +Two traps stacked on that one: + +- **Never pipe the build.** `npm run build | tail -25` exits with *tail's* + status, so a failed build reports success. Redirect to a file and read `$?`, + or run it unpiped. +- **A build error naming a route that touches the database is not evidence + about the database.** Read down to `[cause]` before concluding anything + about the environment — the first line names where it broke, not why. + ## Mobile-First Design (MANDATORY) All UI must work on mobile FIRST, then enhance for larger screens.