Menu
Diagnose Lumen CLI or MCP issues — common errors, SQLite problems, search returning no results, compilation failures. TRIGGER when user reports a bug, error, or unexpected behavior.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | debug-lumen |
| description | Diagnose Lumen CLI or MCP issues — common errors, SQLite problems, search returning no results, compilation failures. TRIGGER when user reports a bug, error, or unexpected behavior. |
Systematic debugging for the Lumen knowledge base engine.
| Symptom | First check | Then check |
|---|---|---|
lumen command not found | which lumen → npm link from apps/cli/ | Verify apps/cli/dist/cli.js exists (run pnpm --filter lumen-kb build) |
| MCP server hangs | Expected — stdio servers wait silently for JSON-RPC input | Test with: printf '{"jsonrpc":"2.0","id":1,...}' | lumen --mcp |
| Search returns nothing | lumen status — are there sources/chunks? | Check if FTS5 index exists: sqlite3 ~/.lumen/lumen.db ".tables" |
| Compilation fails | Check API key: lumen config or echo $ANTHROPIC_API_KEY | Check source has chunks: lumen status |
MODULE_NOT_FOUND errors | pnpm install then pnpm rebuild better-sqlite3 | Check if /tmp/lumen-*/node_modules symlinks exist |
| Auth "Invalid origin" | Add the dev port to trustedOrigins in apps/web/src/lib/auth.ts | Check baseURL matches actual URL |
| Web build crashes Node 23 | Known webpack WASM hash bug — use next dev instead | Or install Node 22 LTS for production builds |
lumen status --json # DB accessible? Has data?
lumen search "test" 2>&1 # Search working?
echo '{}' | lumen --mcp # MCP process starts?
LUMEN_DIR env var overrides ~/.lumen — check if it's set in your shellresetDataDir() must be called between vitest tests or the singleton leaks"self-attention" not self-attentioncontentHash() normalizes whitespace before hashing — use it for dedup, not raw sha256()better-sqlite3 v12 requires a native binary rebuild after Node major version changesPre-deploy verification for Lumen monorepo — type check, lint, test, build across all workspaces. TRIGGER when user says deploy, ship, release, pre-merge, or CI check.
Reference for navigating the Lumen turborepo — workspace commands, where things live, cross-app imports. TRIGGER when user asks about project structure, where to put files, or how workspaces connect.
Review changed code for Lumen project conventions — catches gotchas that linters miss like wrong hash function, FTS5 quoting, missing .js extensions, interface instead of type. TRIGGER when user asks to review, check, or audit code they wrote.
Search, query, and explore the Lumen knowledge base via MCP tools. TRIGGER when user invokes /lumen or asks about their knowledge base, sources, concepts, or graph.
Scaffold a new page or component for the Lumen Next.js web app. TRIGGER when user asks to create, add, or build a new page, route, or dashboard section.
Scaffold a new Lumen CLI command following the Commander.js register pattern. TRIGGER when user asks to create, add, or implement a new CLI command or subcommand.