fix(server): serialize startup error so docker logs are debuggable

[buremba]

Summary

Top-level main().catch in packages/server/src/server.ts logged the boot error directly with logger.error({ error }, 'Failed to start server'). When the pino error serializer isn't picked up (older image, bundler tree-shake, or before #767 landed in a given build), pino falls back to plain object serialization — and JSON.stringify(new Error('boom')) returns {} because Error properties are non-enumerable.

Docker users (issue #766) saw exactly this and had zero signal about which env var or config field was wrong:

{"level":"error","msg":"Failed to start server","error":{}}

This PR adds a small serializeBootError(err) walker right at the catch site that pulls out:

• type (constructor name)
• message
• stack
• code (if present, e.g. ECONNREFUSED)
• issues (ZodError field-path array)
• errors (AggregateError children, recursively)
• cause (recursively)

…and logs the result under both err (pino convention) and error (legacy key) so the line is informative regardless of pino config. As a last-resort fallback it also writes a plain-text Failed to start server: <Type>: <message> + stack to stderr, so users whose log shipper only captures stderr or strips structured fields still see the cause.

Reproducer

Pre-fix behavior (what #766 hits):

$ bun -e 'import pino from "pino"; const l = pino(); l.error({error: new Error("ENCRYPTION_KEY is required")}, "Failed to start server")'
{"level":50,"time":...,"error":{},"msg":"Failed to start server"}

Post-fix behavior (same scenario after serializeBootError):

{"level":50,"time":...,
 "err":{"type":"Error","message":"ENCRYPTION_KEY is required","stack":"Error: ENCRYPTION_KEY is required\n    at ..."},
 "error":{...same...},
 "msg":"Failed to start server"}
Failed to start server: Error: ENCRYPTION_KEY is required
Error: ENCRYPTION_KEY is required
    at ...

The original error: {} line is replaced by a fully-structured object with type / message / stack, plus a stderr fallback for docker logs consumers.

Test plan

• bunx tsc --noEmit -p packages/server/tsconfig.json clean
• Pre-commit biome + tsc hook passes
• Manual repro: boot with dotenv.config() returning empty + DATABASE_URL set + no ENCRYPTION_KEY. Pre-fix prints error:{}; post-fix prints full message + stack + stderr fallback line.
• Optional: trigger any other early-boot throw (ZodError, missing DATABASE_URL) and confirm the new fields land.

Fixes #766

Summary by CodeRabbit

• Bug Fixes
  • Improved error reporting and logging when the server fails to start, providing clearer and more structured error information for diagnostics.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: ee096360-1b11-4401-8239-cb6f7c07ed83

📥 Commits

Reviewing files that changed from the base of the PR and between 8102b9e and f56ab94.

📒 Files selected for processing (1)

• packages/server/src/server.ts

---

📝 Walkthrough

Walkthrough

This PR adds a serializeBootError helper function and updates the server's top-level error handler to provide structured, debuggable error output during boot failures. The serializer recursively transforms errors and Zod validation issues into JSON-compatible objects; the catch handler logs both structured and plain-text output before exiting.

Changes

Boot Error Serialization

Layer / File(s)	Summary
Error serialization and logging packages/server/src/server.ts	Introduces serializeBootError to defensively convert boot failures—including nested cause, errors, and Zod issues—into enumerable plain objects. Updates the main().catch handler to serialize errors, log structured JSON under both err and error keys, emit plain-text stderr output with message, type, and stack when available, then exit with status 1.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 Errors wrapped in JSON bright,
No more crashes in the night!
Stack traces flow, nested deep—
Debugging logs the server keep. 🌙

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/printable-startup-error

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!