Troubleshooting Overview
Quick diagnostic checklist, how to read Nebutra error messages, how to increase log verbosity, and how to get help.
Quick diagnostic checklist
Before diving into specific errors, run through this checklist. Most issues are resolved by one of these steps.
pnpm infra:upThis starts PostgreSQL 16, Redis 7, and ClickHouse 24 via Docker Compose. Without these services, database connection errors and queue failures are expected.
pnpm installAfter cloning or pulling new commits, always reinstall. Workspace symlinks can break if packages are added or removed.
Ensure .env.local exists and all required variables are set. See the Environment Variables reference. The app will print the name of any missing required variable on startup.
pnpm db:generateRun this after any change to packages/platform/db/prisma/schema.prisma. A stale Prisma client causes TypeScript type errors and runtime query failures.
rm -rf apps/web/.next apps/landing/.next
pnpm devTurbopack and Webpack both maintain on-disk caches. Stale cache entries can cause module resolution errors that disappear after a clean restart.
pnpm lint:fixBiome auto-fixes most lint errors. If the build fails on lint, this step resolves it.
How to read Nebutra error messages
Nebutra uses structured error messages that follow a consistent format:
Error: [package] Short description of the problem
at functionName (file.ts:line)
Context:
variable: value
tenantId: org_xxxThe [package] prefix tells you which package threw the error. Common prefixes:
| Prefix | Package | What it means |
|---|---|---|
[config] | @nebutra/config | Missing or invalid environment variable |
[tenant] | @nebutra/tenant | Tenant context not initialised |
[queue] | @nebutra/queue | Message queue connection or handler error |
[search] | @nebutra/search | Search provider connection error |
[vault] | @nebutra/vault | Encryption key misconfiguration |
Increasing log verbosity
Set the LOG_LEVEL environment variable to see more detail:
LOG_LEVEL=debugValid levels (least to most verbose): error → warn → info → debug.
The default level is info in development and warn in production. Debug output includes:
- All outgoing HTTP requests from the API gateway
- Queue job enqueue and dequeue events
- Tenant context resolution steps
- Config validation details
Do not use LOG_LEVEL=debug in production. Debug output contains internal request details that should not appear in production logs.
Getting help
How to submit a good bug report
A useful bug report includes the following:
- The exact error message — copy the full stack trace, not a paraphrase.
- Reproduction steps — the minimum sequence of actions that triggers the error.
- Environment — Node.js version, pnpm version, OS, and which app (
web,api-gateway, etc.). - What you expected vs what actually happened.
- What you already tried from the checklist above.
# Collect environment info quickly
node --version && pnpm --version && uname -aRelated
How is this guide?
Last updated on