gastownhall/beads · error

recovery: %w

Error message

recovery: %w

What it means

Returned by RecoverPreV56DoltDir when the removal of the legacy pre-0.56 .dolt/ directory succeeded but the subsequent reinitialization via ensureDoltInit failed. This means the old database was deleted (data was unrecoverable anyway per GH#2137) but no fresh database was created — bd is left without an initialized dolt directory. The wrapped error is the underlying ensureDoltInit failure (directory creation or dolt init).

Source

Thrown at internal/doltserver/doltserver.go:1987

		return false, nil // No .dolt/ directory — nothing to recover
	}

	markerPath := filepath.Join(doltDir, bdDoltMarker)
	if _, err := os.Stat(markerPath); err == nil {
		return false, nil // Marker exists — database is from 0.56+
	}

	fmt.Fprintf(os.Stderr, "Detected dolt database from an older bd version (pre-0.56).\n")
	fmt.Fprintf(os.Stderr, "Rebuilding dolt database at %s ...\n", doltDir)

	if err := os.RemoveAll(dotDolt); err != nil {
		return false, fmt.Errorf("cannot remove old dolt database at %s: %w\n\n"+
			"Manually delete %s and retry", dotDolt, err, dotDolt)
	}

	// Reinitialize
	if err := ensureDoltInit(doltDir); err != nil {
		return true, fmt.Errorf("recovery: %w", err)
	}

	return true, nil
}

// IsPreV56DoltDir returns true if doltDir contains a .dolt/ directory that
// was NOT created by bd 0.56+ (missing .bd-dolt-ok marker). These databases
// were created by the old embedded Dolt mode and may be incompatible.
// Used by doctor checks to detect potentially problematic dolt databases.
func IsPreV56DoltDir(doltDir string) bool {
	dotDolt := filepath.Join(doltDir, ".dolt")
	if _, err := os.Stat(dotDolt); os.IsNotExist(err) {
		return false // No .dolt/ at all
	}
	markerPath := filepath.Join(doltDir, bdDoltMarker)
	_, err := os.Stat(markerPath)
	return os.IsNotExist(err)
}

View on GitHub (pinned to 71377f2769)

Solutions

1. Read the wrapped cause: if it is the 'dolt init' error, install/repair the dolt binary and verify with `dolt version`
2. If the wrapped cause is a filesystem error, fix writability/space on doltDir, then re-run bd to retry recovery
3. If recovery left a broken partial state, delete .beads/.dolt and any partial files, then re-run bd to reinitialize from scratch
4. Once dolt works, confirm the .bd-dolt-ok marker exists in doltDir so future runs skip recovery

Example fix

// before (recovery deleted .dolt but 'dolt' binary missing)
# error: recovery: dolt init: exec: "dolt": executable file not found in $PATH
// after
$ curl -L https://github.com/dolthub/dolt/releases/latest/download/dolt-linux-amd64.tar.gz | tar -xz
$ mv dolt-linux-amd64/dolt /usr/local/bin/
$ bd ready   # ensureDoltInit runs 'dolt init' successfully

if IsPreV56DoltDir(doltDir) {
    if _, err := exec.LookPath("dolt"); err != nil {
        return fmt.Errorf("pre-0.56 database detected but dolt CLI missing; install dolt BEFORE triggering recovery")
    }
    if err := os.MkdirAll(doltDir, 0o755); err != nil {
        return fmt.Errorf("dolt dir not writable; recovery will fail after deleting .dolt: %w", err)
    }
}

performed, err := RecoverPreV56DoltDir(doltDir)
if err != nil && strings.HasPrefix(err.Error(), "recovery:") {
    // .dolt was already deleted; fix the cause (install dolt / fix perms) and retry safely
    if rerr := ensureDoltInit(doltDir); rerr == nil {
        return nil // recovered on retry
    }
    return err
}

When it happens

Trigger: RecoverPreV56DoltDir removes an old .dolt/ directory during a pre-0.56 upgrade, then ensureDoltInit fails — e.g. MkdirAll fails on a read-only/full filesystem, or 'dolt init' exits non-zero because the dolt binary is missing, too old, or rejects the directory.

Common situations: Upgrading bd to 0.56+ on a machine without the dolt CLI installed (the old embedded mode did not need it); half-completed recovery after fixing a partial removal permission issue; container image lacking the dolt binary.

Related errors

• dolt init: %w %s
• cannot remove old dolt database at %s: %w Manually delete %
• multiple .doltcfg directories detected
• dolt directory is required
• dolt binary not found

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