gastownhall/beads · error

create branch %s: %w

Error message

create branch %s: %w

What it means

CreateBranch runs CALL DOLT_BRANCH(?) to create a branch from the current HEAD and wraps failures as 'create branch <name>: %w'. Dolt rejects the call when the branch name already exists, is invalid, or when the connection/session is unhealthy. The name is included so the failing branch is identifiable.

Source

Thrown at internal/storage/versioncontrolops/branches.go:39

		}
		branches = append(branches, name)
	}
	return branches, rows.Err()
}

// CurrentBranch returns the name of the active branch.
func CurrentBranch(ctx context.Context, db DBConn) (string, error) {
	var branch string
	if err := db.QueryRowContext(ctx, "SELECT active_branch()").Scan(&branch); err != nil {
		return "", fmt.Errorf("get current branch: %w", err)
	}
	return branch, nil
}

// CreateBranch creates a new Dolt branch from the current HEAD.
func CreateBranch(ctx context.Context, db DBConn, name string) error {
	if _, err := db.ExecContext(ctx, "CALL DOLT_BRANCH(?)", name); err != nil {
		return fmt.Errorf("create branch %s: %w", name, err)
	}
	return nil
}

// DeleteBranch force-deletes a Dolt branch.
func DeleteBranch(ctx context.Context, db DBConn, name string) error {
	if _, err := db.ExecContext(ctx, "CALL DOLT_BRANCH('-D', ?)", name); err != nil {
		return fmt.Errorf("delete branch %s: %w", name, err)
	}
	return nil
}

// CheckoutBranch switches the active session to the named branch.
func CheckoutBranch(ctx context.Context, db DBConn, name string) error {
	if _, err := db.ExecContext(ctx, "CALL DOLT_CHECKOUT(?)", name); err != nil {
		return fmt.Errorf("checkout branch %s: %w", name, err)
	}
	return nil

View on GitHub (pinned to 71377f2769)

Solutions

1. Check existence first (CurrentBranch + querying dolt_branches) and skip creation if the branch already exists
2. Sanitize/validate the branch name (no spaces, valid ref characters) before calling
3. Handle the duplicate-branch case as a no-op success by inspecting the wrapped driver error

Example fix

// before
err := versioncontrolops.CreateBranch(ctx, db, name)
// after
exists, _ := branchExists(ctx, db, name)
if !exists {
    err := versioncontrolops.CreateBranch(ctx, db, name)
}

var count int
_ = db.QueryRowContext(ctx,
    "SELECT COUNT(*) FROM dolt_branches WHERE name = ?", name).Scan(&count)
// count > 0 means branch already exists; skip CreateBranch

err := versioncontrolops.CreateBranch(ctx, db, name)
if err != nil {
    if strings.Contains(err.Error(), "already exists") || strings.Contains(err.Error(), "duplicate") {
        return nil // treat as success
    }
    return fmt.Errorf("create branch %s: %w", name, err)
}

When it happens

Trigger: Calling CreateBranch with a name that already exists (DOLT_BRANCH without -c/force fails on duplicates), an illegal branch name, or when the Dolt call errors from a connection issue.

Common situations: Re-running an init/branch bootstrap on an already-initialized repo; branch names with spaces or invalid characters; concurrent workers racing to create the same branch; stale connections after server restart.

Related errors

• get current branch: %w
• failed to begin transaction: %w
• failed to recompute is_blocked: %w
• failed to commit is_blocked repairs: %w
• failed to query orphaned dependencies: %w

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/0d5245a7eaca7ec3. Report an issue: GitHub.