{"record":{"id":"2fb27bcebd4e9d67","repo":"gastownhall/beads","slug":"start-database-server-w","errorCode":null,"errorMessage":"start database server: %w","messagePattern":"start database server: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"internal/storage/dbproxy/proxy/server.go","lineNumber":267,"sourceCode":"\t\tidentMu.RLock()\n\t\tdefer identMu.RUnlock()\n\t\treturn identReply\n\t})\n\tif err != nil {\n\t\treturn fmt.Errorf(\"start control listener: %w\", err)\n\t}\n\tdefer func() { _ = control.Close() }()\n\n\tp.stats.IncBackendStart()\n\tif err := p.server.Start(ctx); err != nil {\n\t\t// Start failed with no backend left running (Start cleans up its own\n\t\t// failure), so there is no teardown to move off the lock; classifying\n\t\t// the epoch-watcher cancellation just keeps the child's exit reason\n\t\t// precise for the spawning parent.\n\t\tif changed, cerr := stopEpochChanged(p.rootDir, p.stopEpoch); cerr == nil && changed {\n\t\t\treturn fmt.Errorf(\"%w for %s: stop epoch advanced during backend start (%v)\", errStartInterrupted, p.rootDir, err)\n\t\t}\n\t\treturn fmt.Errorf(\"start database server: %w\", err)\n\t}\n\n\tif err := waitForServerReady(ctx, p.server, serverReadyTimeout); err != nil {\n\t\tif changed, cerr := stopEpochChanged(p.rootDir, p.stopEpoch); cerr == nil && changed {\n\t\t\treturn abortInterruptedStart()\n\t\t}\n\t\tp.stats.IncBackendStop()\n\t\t_ = stopBackendBounded(p.server)\n\t\treturn fmt.Errorf(\"database server not ready: %w\", err)\n\t}\n\tbirth, err := procid.Capture(os.Getpid())\n\tif err != nil {\n\t\tp.stats.IncBackendStop()\n\t\t_ = stopBackendBounded(p.server)\n\t\treturn fmt.Errorf(\"capture proxy birth identity: %w\", err)\n\t}\n\trootID, err := identity.RootID(p.rootDir)\n\tif err != nil {","sourceCodeStart":249,"sourceCodeEnd":285,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/dbproxy/proxy/server.go#L249-L285","documentation":"Wraps a genuine failure from p.server.Start(ctx) - the database backend process failed to boot - when the stop epoch has NOT advanced, so it cannot be blamed on concurrent shutdown. The underlying cause (exec failure, config error, database open error) is preserved via %w.","triggerScenarios":"ListenAndServe -> p.server.Start(ctx) returns an error and stopEpochChanged reports no change: the backend itself failed to start (bad dsn, missing binary, corrupt database, port conflicts on the backend).","commonSituations":"Database binary missing or wrong version after upgrade; corrupt or locked database files in rootDir; insufficient memory/file descriptors; invalid server configuration; backend's own listener port already taken.","solutions":["Unwrap the error (errors.Unwrap / %v shows the child cause) and fix the reported backend problem","Verify the database server binary exists and is executable with the expected version","Check backend logs and database file integrity in rootDir","Ensure adequate resources (fd limits, memory) for the backend process"],"exampleFix":"// before\nerr := p.ListenAndServe(ctx)\nlog.Println(err) // \"start database server: exec: no such file\"\n// after\nif err := p.ListenAndServe(ctx); err != nil {\n    var pathErr *exec.Error\n    if errors.As(err, &pathErr) {\n        log.Fatalf(\"backend binary missing: %v\", pathErr)\n    }\n    log.Fatal(err)\n}","handlingStrategy":"try-catch","validationCode":"// Before start, sanity-check the backend prerequisites\nif _, err := os.Stat(serverBinary); err != nil {\n    return fmt.Errorf(\"backend binary missing: %w\", err)\n}\nif err := os.Chmod(serverBinary, 0o755); err != nil { return err }","typeGuard":null,"tryCatchPattern":"err := p.ListenAndServe(ctx)\nif err != nil && !errors.Is(err, errStartInterrupted) {\n    log.Fatalf(\"backend failed to start: %v\", err) // %v reveals the wrapped child cause\n}","preventionTips":["Pin and verify the backend binary version in deploy scripts","Run integrity checks on database files before starting","Enforce adequate ulimits (nofile, memory) for the backend process"],"tags":["backend","startup","process","database"],"backgroundTag":"backend-start-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}