{"record":{"id":"4eef9b8abea7123f","repo":"gastownhall/beads","slug":"acquire-connection-for-checkout-w","errorCode":null,"errorMessage":"acquire connection for checkout: %w","messagePattern":"acquire connection for checkout: %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/dolt/store.go","lineNumber":4839,"sourceCode":"\tif err != nil {\n\t\treturn fmt.Errorf(\"acquire connection for branch: %w\", err)\n\t}\n\tdefer conn.Close()\n\treturn versioncontrolops.CreateBranch(ctx, conn, name)\n}\n\n// Checkout switches to the specified branch\nfunc (s *DoltStore) Checkout(ctx context.Context, branch string) (retErr error) {\n\tctx, span := doltTracer.Start(ctx, \"dolt.checkout\",\n\t\ttrace.WithSpanKind(trace.SpanKindClient),\n\t\ttrace.WithAttributes(append(s.doltSpanAttrs(),\n\t\t\tattribute.String(\"dolt.branch\", branch),\n\t\t)...),\n\t)\n\tdefer func() { endSpan(span, retErr) }()\n\tconn, err := s.db.Conn(ctx)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"acquire connection for checkout: %w\", err)\n\t}\n\tdefer conn.Close()\n\tif err := versioncontrolops.CheckoutBranch(ctx, conn, branch); err != nil {\n\t\treturn err\n\t}\n\ts.branch = branch\n\treturn nil\n}\n\n// Merge merges the specified branch into the current branch.\n// Returns any merge conflicts if present. Implements storage.VersionedStorage.\nfunc (s *DoltStore) Merge(ctx context.Context, branch string) (conflicts []storage.Conflict, retErr error) {\n\tctx, span := doltTracer.Start(ctx, \"dolt.merge\",\n\t\ttrace.WithSpanKind(trace.SpanKindClient),\n\t\ttrace.WithAttributes(append(s.doltSpanAttrs(),\n\t\t\tattribute.String(\"dolt.merge_branch\", branch),\n\t\t)...),\n\t)","sourceCodeStart":4821,"sourceCodeEnd":4857,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/dolt/store.go#L4821-L4857","documentation":"Checkout requires a dedicated pooled connection so the Dolt session's branch context is consistent. This wraps a failure from s.db.Conn(ctx) when acquiring the connection used by versioncontrolops.CheckoutBranch. Same mechanics as pool acquisition failures everywhere: exhausted pool, cancelled context, or dead backend.","triggerScenarios":"Calling the store's checkout method (traced with dolt.branch attribute) when s.db.Conn(ctx) returns an error before CheckoutBranch runs — pool exhausted (notably MaxOpenConns:1 with another pinned connection), ctx expired waiting in the pool queue, or the Dolt server is down.","commonSituations":"Concurrent vc checkout/merge commands under a single-connection pool; watchdog-killed long requests whose context expires mid-wait; server maintenance windows.","solutions":["Release other pinned connections (close rows, conns, txs) before checkout.","Raise MaxOpenConns or serialize branch operations.","Verify ctx is alive before calling checkout; use a fresh context for control-plane operations.","Check Dolt server availability and pool health (db.Ping).","Retry the checkout; stale connections are evicted from the pool."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"if err := ctx.Err(); err != nil { return err }\nif err := db.PingContext(ctx); err != nil { return err }","typeGuard":null,"tryCatchPattern":"conn, err := s.db.Conn(ctx)\nif err != nil {\n    if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {\n        return fmt.Errorf(\"checkout cancelled waiting for connection: %w\", err)\n    }\n    return fmt.Errorf(\"acquire connection for checkout: %w\", err)\n}\ndefer conn.Close()","preventionTips":["Release rows/connections before starting checkout","Increase pool size for concurrent vc commands","Check ctx deadlines before pool-dependent calls","Monitor db.Stats().WaitCount for pool contention"],"tags":["dolt","connection-pool","checkout","database"],"backgroundTag":"connection-acquisition-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}