{"record":{"id":"dc1727ee22b20221","repo":"gastownhall/beads","slug":"checkout-branch-s-w","errorCode":null,"errorMessage":"checkout branch %s: %w","messagePattern":"checkout branch (.+?): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/versioncontrolops/branches.go","lineNumber":55,"sourceCode":"func CreateBranch(ctx context.Context, db DBConn, name string) error {\n\tif _, err := db.ExecContext(ctx, \"CALL DOLT_BRANCH(?)\", name); err != nil {\n\t\treturn fmt.Errorf(\"create branch %s: %w\", name, err)\n\t}\n\treturn nil\n}\n\n// DeleteBranch force-deletes a Dolt branch.\nfunc DeleteBranch(ctx context.Context, db DBConn, name string) error {\n\tif _, err := db.ExecContext(ctx, \"CALL DOLT_BRANCH('-D', ?)\", name); err != nil {\n\t\treturn fmt.Errorf(\"delete branch %s: %w\", name, err)\n\t}\n\treturn nil\n}\n\n// CheckoutBranch switches the active session to the named branch.\nfunc CheckoutBranch(ctx context.Context, db DBConn, name string) error {\n\tif _, err := db.ExecContext(ctx, \"CALL DOLT_CHECKOUT(?)\", name); err != nil {\n\t\treturn fmt.Errorf(\"checkout branch %s: %w\", name, err)\n\t}\n\treturn nil\n}\n","sourceCodeStart":37,"sourceCodeEnd":59,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/versioncontrolops/branches.go#L37-L59","documentation":"CheckoutBranch runs CALL DOLT_CHECKOUT(?) to switch the session's active branch and wraps failures as 'checkout branch <name>: %w'. Because Dolt checkout is session-scoped, failure means the session stays on the old branch. Dolt rejects checkout when the branch doesn't exist or when uncommitted working-set changes would conflict with the switch.","triggerScenarios":"Calling CheckoutBranch for a branch that doesn't exist; switching while the session has dirty working-set changes that block the switch; using a pooled connection so the checkout affects the wrong session or the error arises from a dead connection.","commonSituations":"Typo in branch name; dirty tables from an earlier failed commit; running against a connection pool instead of a single dedicated connection (session state mismatch); branch deleted by another process.","solutions":["Commit or stash pending changes (StageAndCommit / DOLT_RESET) before checkout","Confirm the branch exists (query dolt_branches) before checkout","Use a single dedicated connection for checkout and subsequent session-scoped operations, not a pooled *sql.DB"],"exampleFix":"// before\nerr := versioncontrolops.CheckoutBranch(ctx, pooledDB, \"feature\")\n// after\nconn := db.Conn(ctx) // dedicated session\n_, _ = conn.ExecContext(ctx, \"CALL DOLT_ADD('-A')\")\nerr := versioncontrolops.CheckoutBranch(ctx, conn, \"feature\")","handlingStrategy":"validation","validationCode":"var exists int\n_ = db.QueryRowContext(ctx,\n    \"SELECT COUNT(*) FROM dolt_branches WHERE name = ?\", name).Scan(&exists)\n// require exists == 1 before checkout","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Commit or reset pending changes before switching branches","Use a single dedicated connection (not a pool) for checkout and later session-scoped Dolt calls","Verify the branch exists before checkout","Avoid checking out branches concurrently mutated by other sessions"],"tags":["dolt","sql","branch","session"],"backgroundTag":"dolt-branch-operation-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}