{"record":{"id":"18651f8f5d689b21","repo":"gastownhall/beads","slug":"acquire-connection-for-gc-w","errorCode":null,"errorMessage":"acquire connection for gc: %w","messagePattern":"acquire connection for gc: %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/dolt/store.go","lineNumber":2877,"sourceCode":"\tif s.localActiveDatabaseDir == \"\" {\n\t\treturn 0, &storage.ErrUnsupported{\n\t\t\tOp:      \"ActiveDatabaseSize\",\n\t\t\tBackend: \"dolt-server\",\n\t\t}\n\t}\n\tsize, err := storage.MeasureDirectorySize(ctx, s.localActiveDatabaseDir)\n\tif err != nil {\n\t\treturn 0, fmt.Errorf(\"measure active database directory %q: %w\", s.localActiveDatabaseDir, err)\n\t}\n\treturn size, nil\n}\n\n// DoltGC runs Dolt garbage collection to reclaim disk space.\n// Pins a single connection to avoid session state loss on pooled *sql.DB.\nfunc (s *DoltStore) DoltGC(ctx context.Context) error {\n\tconn, err := s.db.Conn(ctx)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"acquire connection for gc: %w\", err)\n\t}\n\tdefer conn.Close()\n\treturn versioncontrolops.DoltGC(ctx, conn)\n}\n\n// ListRemoteRefs returns the names of all cached remote-tracking refs.\nfunc (s *DoltStore) ListRemoteRefs(ctx context.Context) ([]string, error) {\n\treturn versioncontrolops.ListRemoteRefs(ctx, s.db)\n}\n\n// PruneRemoteRefs deletes all cached remote-tracking refs so a post-squash GC\n// can reclaim the history they anchor (bd-agctw). Returns the deleted names.\nfunc (s *DoltStore) PruneRemoteRefs(ctx context.Context) ([]string, error) {\n\tconn, err := s.db.Conn(ctx)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"acquire connection for remote-ref prune: %w\", err)\n\t}\n\tdefer conn.Close()","sourceCodeStart":2859,"sourceCodeEnd":2895,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/dolt/store.go#L2859-L2895","documentation":"DoltGC pins a single pooled connection before delegating to versioncontrolops.DoltGC, because GC depends on session state that pooled connections would lose; this error wraps failure to acquire that connection from the *sql.DB pool. The actual GC has not started — this is purely pool-acquisition failure.","triggerScenarios":"Calling DoltGC(ctx) when db.Conn(ctx) fails: ctx canceled/timed out while waiting for a free connection, pool exhausted by long-running queries, server unreachable so new dial fails, driver ErrBadConn loop.","commonSituations":"Running GC concurrently with heavy workload saturating the pool; application shutdown canceling ctx; Dolt server restarted; network partition.","solutions":["Retry DoltGC when the pool is less loaded; run GC during quiet periods","Check the wrapped error: context.DeadlineExceeded → raise timeout; dial errors → verify server up and DSN correct","Avoid holding many long transactions concurrently with GC calls","Ensure ctx passed to DoltGC has adequate timeout"],"exampleFix":"// before\nerr := store.DoltGC(ctx) // caller's short ctx\n// after\ngcCtx, cancel := context.WithTimeout(context.Background(), 10*time.Minute)\ndefer cancel()\nerr := store.DoltGC(gcCtx)","handlingStrategy":"retry","validationCode":"// ensure pool is healthy before GC\nif err := store.PingContext(ctx); err != nil {\n    return fmt.Errorf(\"skip GC, server unreachable: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"// Go: retry pool acquisition with backoff\nvar lastErr error\nfor i := 0; i < 3; i++ {\n    if err := store.DoltGC(ctx); err == nil {\n        break\n    } else if errors.Is(err, context.DeadlineExceeded) {\n        lastErr = err\n        time.Sleep(time.Duration(1<<i) * time.Second)\n        continue\n    }\n    return err\n}","preventionTips":["Run GC in maintenance windows with low pool contention","Pass a long-timeout context to GC (it can be slow)","Avoid canceling ctx during shutdown before GC finishes","Ping the server before scheduled GC runs"],"tags":["go","database","connection-pool","dolt","garbage-collection"],"backgroundTag":"connection-acquisition-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}