gastownhall/beads · error

add replacement CLI remote failed; previous URL %q restored:

Error message

add replacement CLI remote failed; previous URL %q restored: %w

What it means

EnsureCLIRemote failed to add the replacement URL, but successfully restored the previous URL via AddCLIRemote. This error reports the original add failure while assuring the caller that the CLI remote still points at the old URL — the system is back in its prior, consistent state.

Source

Thrown at internal/storage/doltutil/remotes.go:233

	defer lock.Unlock()

	current := FindCLIRemote(dbPath, name)
	if RemoteURLsMatch(current, url) {
		return nil
	}
	if current != "" {
		if err := RemoveCLIRemote(dbPath, name); err != nil {
			return err
		}
	}
	if err := AddCLIRemote(dbPath, name, url); err != nil {
		if current == "" {
			return err
		}
		if restoreErr := AddCLIRemote(dbPath, name, current); restoreErr != nil {
			return fmt.Errorf("add replacement CLI remote failed: %w; additionally failed to restore previous URL %q: %v", err, current, restoreErr)
		}
		return fmt.Errorf("add replacement CLI remote failed; previous URL %q restored: %w", current, err)
	}
	return nil
}

View on GitHub (pinned to 71377f2769)

Solutions

1. The previous URL was restored — no repair is needed; fix the new URL.
2. Check the wrapped inner error for dolt's reason (shown via 'dolt remote add failed: <output>').
3. Validate the new URL with remotecache.ValidateRemoteURL and confirm the target repo exists/is reachable, then call EnsureCLIRemote again.
4. If migrating intentionally, run dolt remote add <name> <new-url> manually in dbPath to see the raw CLI error.

Example fix

// before (URL dolt rejects)
err := doltutil.EnsureCLIRemote(dbPath, "origin", "htp:/bad-url/repo")
// after
newURL := "https://doltremoteapi.dolthub.com/org/repo"
if err := remotecache.ValidateRemoteURL(newURL); err == nil {
    err = doltutil.EnsureCLIRemote(dbPath, "origin", newURL)
}

if err := remotecache.ValidateRemoteURL(newURL); err != nil {
    return fmt.Errorf("skip migration, URL invalid: %w", err)
}
err := doltutil.EnsureCLIRemote(dbPath, name, newURL)

err := doltutil.EnsureCLIRemote(dbPath, name, newURL)
if err != nil {
    var wrapped *fmt.WrapError
    _ = err // old URL was restored; safe to fix newURL and retry
    if strings.Contains(err.Error(), "restored") {
        // retry after correcting newURL
        err = doltutil.EnsureCLIRemote(dbPath, name, correctedURL)
    }
}

When it happens

Trigger: Calling EnsureCLIRemote with a changed URL where dolt remote add <name> <new-url> fails (dolt CLI error, invalid URL for dolt, transient failure) but re-adding the old URL succeeds.

Common situations: Pointing the remote at a new URL that dolt rejects (bad format, unreachable host baked into URL) while the old remote remains valid; typos when migrating remotes; dolt CLI transient failures.

Related errors

• remote target %s is non-empty but is neither a bare git repo
• list existing remotes: %w
• add remote %s: %w
• remove existing remote %s: %w
• invalid --dolt-auto-commit=%q (valid: off, on, batch)

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