gastownhall/beads · error

remote-migrate gate: read remotes: %w

Error message

remote-migrate gate: read remotes: %w

What it means

This error wraps a failure while reading the configured Dolt remotes (`dolt_remotes`) during the remote-migrate safety gate. The gate must know whether any remote is configured before allowing a destructive remote-migration flow, and this error means the remotes themselves could not be read from the database.

Source

Thrown at internal/storage/schema/remote_migrate_gate.go:420

	current, err := CurrentVersion(ctx, db)
	if err != nil {
		return fmt.Errorf("remote-migrate gate: read current version: %w", err)
	}
	if current == 0 {
		return nil // fresh database — nothing to fork
	}

	pending, err := PendingVersions(ctx, db)
	if err != nil {
		return fmt.Errorf("remote-migrate gate: read pending versions: %w", err)
	}
	if len(pending) == 0 {
		return nil // already current — nothing to migrate
	}

	hasRemote, err := anyDoltRemoteConfigured(ctx, db)
	if err != nil {
		return fmt.Errorf("remote-migrate gate: read remotes: %w", err)
	}
	// dolt_remotes can read empty even when a remote is configured: a freshly
	// (auto-)started server has not yet synced CLI remotes from .dolt/config
	// (GH#2315). Consult the caller's on-disk probe before allowing migration.
	if !hasRemote && extraHasRemote != nil {
		hasRemote = extraHasRemote()
	}
	if !hasRemote {
		return nil // no remote — no cross-clone fork risk
	}

	// Programmatic override — set by `bd migrate --force` / `bd migrate schema
	// --force` in the root PersistentPreRunE before both
	// autoMigrateOnVersionBump and the main store open. Process-local by
	// design: unlike os.Setenv(AllowRemoteMigrateEnv), it cannot leak into
	// child processes (git hooks, dolt subprocesses). Consulted here — only
	// once the gate would otherwise fire — so normal opens produce no noise.
	if forceAllowRemoteMigrate {

View on GitHub (pinned to 71377f2769)

Solutions

1. Check the wrapped cause (%w) — most often a transient DB/server issue; retry after confirming the Dolt server is up and responsive
2. Run `bd doctor` or a direct `SELECT * FROM dolt_remotes` against the database to confirm the remotes table is readable
3. If corruption is suspected, restore from a recent backup or re-clone the repo
4. File an issue if it reproduces consistently on a healthy database

Example fix

// before: gate fails with opaque wrapped error
err := CheckRemoteMigrateGate(ctx, db)
// after: probe server health and retry the gate
if err := waitForDoltServer(ctx, db); err != nil { return err }
err := CheckRemoteMigrateGate(ctx, db)

// probe that remotes are readable before running the gate
var n int
if err := db.QueryRowContext(ctx, "SELECT COUNT(*) FROM dolt_remotes").Scan(&n); err != nil {
	return fmt.Errorf("dolt_remotes not readable yet: %w", err)
}

err := CheckRemoteMigrateGate(ctx, db)
if err != nil {
	var retryable bool
	if strings.Contains(err.Error(), "read remotes") { retryable = true }
	if retryable { time.Sleep(backoff); retry() }
}

When it happens

Trigger: Calling any of CheckRemoteMigrateGate, CheckRemoteMigrateGateWithAdopt, CheckRemoteMigrateGateWithRemoteCheck, CheckRemoteMigrateGateForRemoteWithRemoteCheck, or CheckRemoteMigrateGateForRemoteWithRemoteCheckAndAdopt when pending migrations exist and the internal `anyDoltRemoteConfigured` query against the remotes table fails (e.g. locked DB, corrupted metadata, server not ready).

Common situations: Dolt SQL server freshly started and not yet serving the remotes table; transient connection loss mid-gate; database corruption; running the gate concurrently with another writer holding locks.

Related errors

• clone from %s succeeded, but the database needs %d schema %s
• reading gate %s: %w
• read labels for %s: %w
• copy label %q for %s: %w
• read dependencies for %s: %w

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