What causes "force push to %s/%s: %w" in gastownhall/beads?

Verify the remote exists with bd vc remote list (SELECT name, url FROM dolt_remotes) and that the branch name is exact.

force push to %s/%s: %w

Error message

force push to %s/%s: %w

What it means

ForcePush wraps a failed CALL DOLT_PUSH('--force', remote, branch) against the embedded Dolt engine with "force push to <remote>/<branch>: <underlying>". The library throws it because the remote-side or engine-side push operation returned an error and ForcePush must attribute it to the specific remote/branch pair. Common underlying causes are authentication failures (missing DOLT_REMOTE_PASSWORD / wrong --user), unknown remote or branch, network failures reaching the remote, and non-fast-forward rejections when the remote enforces protections despite --force.

Source

Thrown at internal/storage/versioncontrolops/remotes.go:93

	if err != nil {
		return fmt.Errorf("push to %s/%s: %w", remote, branch, err)
	}
	return nil
}

// ForcePush force-pushes the given branch to the named remote.
// See Push for the user/auth contract.
func ForcePush(ctx context.Context, db DBConn, remote, branch, user string) error {
	err := withRemoteEnvGuards(func() error {
		if user != "" {
			_, err := db.ExecContext(ctx, "CALL DOLT_PUSH('--force', '--user', ?, ?, ?)", user, remote, branch)
			return err
		}
		_, err := db.ExecContext(ctx, "CALL DOLT_PUSH('--force', ?, ?)", remote, branch)
		return err
	})
	if err != nil {
		return fmt.Errorf("force push to %s/%s: %w", remote, branch, err)
	}
	return nil
}

// Pull pulls changes from the named remote by fetching the branch and merging
// the remote tracking ref. This is equivalent to DOLT_PULL(remote, branch) but
// avoids a nil-pointer panic in embedded Dolt when upstream branch tracking is
// not configured in repo_state.json (GH#3144). The merge runs through
// MergeAndSettle (bd-6dnrw.40), so safe conflict classes are auto-resolved and
// FK cascade violations repaired, matching server-mode pulls.
//
// db must be a single session (see MergeAndSettle). See Push for the
// user/auth contract; only the fetch step authenticates, since the merge step
// is local.
func Pull(ctx context.Context, db DBConn, remote, branch, user string) error {
	return PullWithStrategy(ctx, db, remote, branch, user, "")
}

View on GitHub (pinned to 71377f2769)

Solutions

Verify the remote exists with bd vc remote list (SELECT name, url FROM dolt_remotes) and that the branch name is exact.
Ensure DOLT_REMOTE_PASSWORD is set in the in-process Dolt server's environment, or pass a non-empty user so DOLT_PUSH('--force','--user',...) is used.
Inspect the wrapped underlying error: for auth errors fix credentials; for unknown-remote add the remote; for network errors retry after connectivity is restored.
If the remote rejects non-fast-forward with branch protections, coordinate with the remote admin rather than retrying.

Example fix

// before
err := versioncontrolops.ForcePush(ctx, db, "origin", "main", "") // no creds, empty user
// after
os.Setenv("DOLT_REMOTE_PASSWORD", token) // in the server process env
err := versioncontrolops.ForcePush(ctx, db, "origin", "main", "admin")

Defensive patterns

Strategy: try-catch

Validate before calling

var remotes []storage.RemoteInfo
remotes, err := versioncontrolops.ListRemotes(ctx, db)
if err != nil { return err }
found := false
for _, r := range remotes {
    if r.Name == remote { found = true }
}
if !found { return fmt.Errorf("remote %q not configured", remote) }
if os.Getenv("DOLT_REMOTE_PASSWORD") == "" && user == "" {
    return fmt.Errorf("push to %s needs --user and DOLT_REMOTE_PASSWORD", remote)
}

Type guard

func isForcePushErr(err error) (remote, branch string, ok bool) {
    if err == nil { return "", "", false }
    msg := err.Error()
    if !strings.HasPrefix(msg, "force push to ") { return "", "", false }
    rest := strings.TrimPrefix(msg, "force push to ")
    i := strings.Index(rest, ": ")
    if i < 0 { return "", "", false }
    parts := strings.SplitN(rest[:i], "/", 2)
    if len(parts) != 2 { return "", "", false }
    return parts[0], parts[1], true
}

Try / catch

err := versioncontrolops.ForcePush(ctx, db, remote, branch, user)
if err != nil {
    var opErr *net.OpError
    if errors.As(err, &opErr) {
        // network problem: retry after connectivity check
    } else if strings.Contains(err.Error(), "authentication") || strings.Contains(err.Error(), "permission") {
        // refresh DOLT_REMOTE_PASSWORD / user and retry once
    }
    return fmt.Errorf("force push failed: %w", err)
}

Prevention

Always call ListRemotes first to confirm the remote name exists before pushing.
Set DOLT_REMOTE_PASSWORD in the server process environment whenever a remote requires auth, and pass the matching user.
Run a cheap Fetch(remote) before ForcePush to validate connectivity and credentials.
Only force-push branches you own; for shared branches prefer Push and resolve divergence locally.

When it happens

Trigger: Calling ForcePush when: the remote name is not configured in dolt_remotes; the branch does not exist locally or remotely; credentials are absent/invalid (remotesapi server enforcing CLONE_ADMIN auth without --user and DOLT_REMOTE_PASSWORD set in the server env); the remote is unreachable; or a Dolt server-side guard still rejects the force update.

Common situations: Recovering a rewritten history after rebase/sync conflicts; network or VPN down during bd dolt push; a teammate rotated remote credentials; pushing to a remote that was added under a different name than passed in.

Related errors

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