What causes "CreateRemote %s: %w" in gastownhall/beads?

Inspect the wrapped cause; if it's a 'remote already exists', remove it first or use UpdateRemote instead.

CreateRemote %s: %w

Error message

CreateRemote %s: %w

What it means

Wraps a failure from remoteRepo.AddRemote when adding a Dolt remote fails (internal/storage/domain/remote.go). The message includes the remote name being created; the underlying repository error is preserved with %w for errors.Is/As inspection.

Source

Thrown at internal/storage/domain/remote.go:44

func NewDoltRemoteUseCase(remoteRepo RemoteSQLRepository) DoltRemoteUseCase {
	return &doltRemoteUseCaseImpl{remoteRepo: remoteRepo}
}

type doltRemoteUseCaseImpl struct {
	remoteRepo RemoteSQLRepository
}

var _ DoltRemoteUseCase = (*doltRemoteUseCaseImpl)(nil)

func (u *doltRemoteUseCaseImpl) CreateRemote(ctx context.Context, name, url string) error {
	if name == "" {
		return fmt.Errorf("CreateRemote: name must not be empty")
	}
	if url == "" {
		return fmt.Errorf("CreateRemote: url must not be empty")
	}
	if err := u.remoteRepo.AddRemote(ctx, name, url); err != nil {
		return fmt.Errorf("CreateRemote %s: %w", name, err)
	}
	return nil
}

func (u *doltRemoteUseCaseImpl) UpdateRemote(ctx context.Context, name, url string) error {
	if name == "" {
		return fmt.Errorf("UpdateRemote: name must not be empty")
	}
	if url == "" {
		return fmt.Errorf("UpdateRemote: url must not be empty")
	}
	// Dolt has no atomic remote update, so this is remove-then-add. Capture
	// the old URL first so a failed add can restore the remote instead of
	// leaving it deleted (bd-6dnrw.44 P3).
	var oldURL string
	if remotes, err := u.remoteRepo.ListRemotes(ctx); err == nil {
		for _, rem := range remotes {
			if rem.Name == name {

View on GitHub (pinned to 71377f2769)

Solutions

Inspect the wrapped cause; if it's a 'remote already exists', remove it first or use UpdateRemote instead.
Run bd remote list (or equivalent) to check for an existing remote with that name.
Verify the database is writable and not locked by another process.
Retry with a fresh context if the error indicates cancellation/timeout.

Example fix

// before
err := uc.CreateRemote(ctx, "origin", url)
if err != nil { return err }
// after
err := uc.CreateRemote(ctx, "origin", url)
if err != nil {
    if strings.Contains(fmt.Sprint(errors.Unwrap(err)), "already") {
        return uc.UpdateRemote(ctx, "origin", url)
    }
    return err
}

Defensive patterns

Strategy: try-catch

Validate before calling

if name == "" || url == "" { return fmt.Errorf("name and url are required") }

Try / catch

err := uc.CreateRemote(ctx, name, url)
if err != nil {
    cause := fmt.Sprint(errors.Unwrap(err))
    if strings.Contains(cause, "already") {
        return uc.UpdateRemote(ctx, name, url)
    }
    return err
}

Prevention

Check existing remotes before adding; use UpdateRemote for existing names.
Make setup scripts idempotent.
Ensure the database directory is writable before remote operations.

When it happens

Trigger: Calling CreateRemote with valid non-empty name/url when AddRemote fails: remote name already exists, underlying Dolt/SQL error, database locked or read-only, or context canceled.

Common situations: Re-running setup scripts that add an already-configured 'origin' remote; the Dolt database directory being read-only; another bd process holding the DB lock.

Related errors

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