{"record":{"id":"6b9b3a7f6c59ba7c","repo":"gastownhall/beads","slug":"database-server-not-running","errorCode":null,"errorMessage":"database server not running","messagePattern":"database server not running","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/dbproxy/proxy/server.go","lineNumber":495,"sourceCode":"\t\tdefer func() { _ = backend.Close() }()\n\t\tdefer func() { _ = client.Close() }()\n\t\tn, err := io.Copy(client, backend)\n\t\tp.stats.AddBytesBackendToClient(n)\n\t\tp.tracef(\"handleConn(%s) backend→client done (n=%d, err=%v)\", addr, n, err)\n\t\treturn err\n\t})\n\treturn g.Wait()\n}\n\nfunc waitForServerReady(ctx context.Context, s server.DatabaseServer, timeout time.Duration) error {\n\tbo := backoff.NewExponentialBackOff()\n\tbo.InitialInterval = readyInitialBackoff\n\tbo.MaxInterval = readyMaxBackoff\n\tbo.MaxElapsedTime = timeout\n\n\treturn backoff.Retry(func() error {\n\t\tif !s.Running(ctx) {\n\t\t\treturn errors.New(\"database server not running\")\n\t\t}\n\t\tdialCtx, cancel := context.WithTimeout(ctx, readyDialTimeout)\n\t\tdefer cancel()\n\t\tconn, err := s.Dial(dialCtx)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t\t_ = conn.Close()\n\t\treturn nil\n\t}, backoff.WithContext(bo, ctx))\n}\n","sourceCodeStart":477,"sourceCodeEnd":507,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/dbproxy/proxy/server.go#L477-L507","documentation":"During readiness waiting, the backoff loop returns this error when s.Running(ctx) reports the database server is not running. It means the backend process failed to start or died before the readiness timeout elapsed, so the proxy cannot accept connections.","triggerScenarios":"Backend Dolt server exits during startup (bad config, port conflict, corrupted DB) while proxy waits for readiness; startup timeout expiring with the server still down.","commonSituations":"Invalid dolt_server config path; port already in use; dolt binary crashing on an incompatible database directory.","solutions":["Check the server log file (passed to NewDoltServer) for the underlying backend crash reason","Verify the Dolt database directory and config file are valid and the port is free","Re-run the dolt binary manually against the rootDir to see startup errors directly"],"exampleFix":"// before\nerr := waitForReady(ctx, 5*time.Second) // opaque 'not running'\n// after\nif err != nil {\n    log.Fatalf(\"backend not ready: %v; see %s\", err, logFilePath)\n}","handlingStrategy":"retry","validationCode":"// pre-check binary and port availability before starting backend\nif _, err := exec.LookPath(doltBin); err != nil { return err }\nif ln, err := net.Listen(\"tcp\", addr); err != nil { return fmt.Errorf(\"port in use: %w\", err) }; ln.Close()","typeGuard":null,"tryCatchPattern":"if err := waitForReady(ctx, timeout); err != nil {\n    if strings.Contains(err.Error(), \"database server not running\") {\n        // inspect backend log, then retry startup with backoff\n        tailServerLog(logFilePath)\n        return retryStart(ctx)\n    }\n    return err\n}","preventionTips":["Always capture and inspect the dolt server log file","Verify database directory and server config validity before launch","Reserve the backend port before startup to avoid silent port conflicts"],"tags":["go","backend","startup"],"backgroundTag":"server-not-running","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}