{"record":{"id":"48d3dbb2f9299d4d","repo":"gastownhall/beads","slug":"acquire-connection-for-branch-w","errorCode":null,"errorMessage":"acquire connection for branch: %w","messagePattern":"acquire connection for branch: %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/dolt/store.go","lineNumber":4822,"sourceCode":"// when (repaired=false, had=true) — unrepaired violations are the operator's.\n// The implementation is shared with the embedded pull path (bd-6dnrw.40); see\n// versioncontrolops.TryRepairFKCascadeViolations for the full contract.\nfunc (s *DoltStore) tryRepairFKCascadeViolations(ctx context.Context, tx *sql.Tx) (repaired, had bool, err error) {\n\treturn versioncontrolops.TryRepairFKCascadeViolations(ctx, tx)\n}\n\n// Branch creates a new branch\nfunc (s *DoltStore) Branch(ctx context.Context, name string) (retErr error) {\n\tctx, span := doltTracer.Start(ctx, \"dolt.branch\",\n\t\ttrace.WithSpanKind(trace.SpanKindClient),\n\t\ttrace.WithAttributes(append(s.doltSpanAttrs(),\n\t\t\tattribute.String(\"dolt.branch\", name),\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 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}","sourceCodeStart":4804,"sourceCodeEnd":4840,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/dolt/store.go#L4804-L4840","documentation":"CreateBranch needs its own connection from the sql.DB pool (so Dolt session variables like branch state stay pinned). This error wraps database/sql's (*sql.DB).Conn failure when acquiring that connection for branch creation. It means the pool could not hand out a connection: pool exhausted, all connections stale, context done, or the database is unreachable.","triggerScenarios":"Calling the store's branch-creation method (traced with dolt.branch attribute) when s.db.Conn(ctx) fails — pool at MaxOpenConns with all connections busy (e.g. MaxOpenConns:1 and another operation holds the connection), or ctx cancelled while waiting for a free connection.","commonSituations":"Test setups or constrained production configs with MaxOpenConns:1 where a prior operation didn't release its connection; long queue of concurrent vc branch calls; Dolt server restart leaving dead pooled connections.","solutions":["Ensure preceding operations release their connections/transactions before creating a branch.","Increase MaxOpenConns in the pool configuration if concurrency demands it.","Check ctx deadline — waiting for a free connection is cancelled by expired contexts.","Ping the Dolt server / restart it if all pooled connections are dead.","Retry; database/sql will prune bad connections from the pool on subsequent attempts."],"exampleFix":"// before\ndb.SetMaxOpenConns(1) // branch creation starves while another conn is held\n// after\ndb.SetMaxOpenConns(4)\ndb.SetConnMaxLifetime(5 * time.Minute)","handlingStrategy":"retry","validationCode":"if err := ctx.Err(); err != nil { return err }\nstats := db.Stats()\nif stats.MaxOpenConnections > 0 && stats.InUse >= stats.MaxOpenConnections { return errors.New(\"connection pool exhausted\") }","typeGuard":null,"tryCatchPattern":"conn, err := s.db.Conn(ctx)\nif err != nil {\n    var waited bool\n    if errors.Is(err, context.DeadlineExceeded) { waited = true }\n    return fmt.Errorf(\"acquire connection for branch (waited=%v): %w\", waited, err)\n}","preventionTips":["Size MaxOpenConns above your maximum concurrent branch operations","Always defer conn.Close()/tx rollback immediately after acquiring","Use bounded timeouts on control-plane contexts","Serialize vc operations in tests with MaxOpenConns:1"],"tags":["dolt","connection-pool","database","branch"],"backgroundTag":"connection-acquisition-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}