gastownhall/beads · error

dolt init: %w %s

Error message

dolt init: %w
%s

What it means

Returned by ensureDoltInit when executing the external 'dolt init' command in a fresh dolt directory exits non-zero; the message includes both the exec error and the combined stdout/stderr output from the dolt CLI. bd shells out to the dolt binary to initialize the repository, so any dolt-side failure (or the binary being unusable) surfaces here.

Source

Thrown at internal/doltserver/doltserver.go:1948

	if err := os.MkdirAll(doltDir, config.BeadsDirPerm); err != nil {
		return fmt.Errorf("creating dolt directory: %w", err)
	}

	dotDolt := filepath.Join(doltDir, ".dolt")

	if _, err := os.Stat(dotDolt); err == nil {
		// .dolt/ exists — seed the marker if missing.
		// This is the non-destructive path: we just mark existing databases
		// as known. The destructive recovery path (RecoverPreV56DoltDir) is
		// triggered separately during version upgrades.
		_ = MarkDoltDirCompatible(doltDir)
		return nil // Already initialized
	}

	cmd := exec.Command("dolt", "init")
	cmd.Dir = doltDir
	if out, err := cmd.CombinedOutput(); err != nil {
		return fmt.Errorf("dolt init: %w\n%s", err, out)
	}

	// Write version marker so future runs know this database is compatible.
	_ = MarkDoltDirCompatible(doltDir)

	return nil
}

// RecoverPreV56DoltDir removes and reinitializes a dolt database that was
// created by a pre-0.56 bd version. Call this during version upgrade detection
// (e.g., from autoMigrateOnVersionBump when previousVersion < 0.56).
//
// Pre-0.56 databases used embedded Dolt mode with a different Dolt library
// version that may produce nil DoltDB values, causing panics (GH#2137).
// The data is unrecoverable — the fix is to start fresh.
//
// Returns true if recovery was performed, false if not needed.
func RecoverPreV56DoltDir(doltDir string) (bool, error) {

View on GitHub (pinned to 71377f2769)

Solutions

1. Install the Dolt CLI (or add it to PATH) and verify: dolt version — bd server mode requires a working dolt binary
2. Read the trailing command output in the error message; it contains dolt's own reason (e.g. 'repository already exists') and address it
3. If the output indicates a corrupt/legacy repo, remove the .dolt directory and let bd reinitialize: rm -rf <doltDir>/.dolt
4. Ensure the dolt binary is recent enough and matches what bd expects (upgrade dolt via its official installer)

Example fix

// before (container without dolt)
# error: dolt init: exec: "dolt": executable file not found in $PATH
// after (Dockerfile)
RUN 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/

out, err := exec.LookPath("dolt")
if err != nil {
    return fmt.Errorf("dolt CLI not found in PATH; install Dolt before running bd server mode")
}
if v, err := exec.Command(out, "version").Output(); err != nil {
    return fmt.Errorf("dolt binary not runnable: %w", err)
} else {
    _ = v
}

if err := ensureDoltInit(doltDir); err != nil {
    var exitErr *exec.ExitError
    if errors.As(err, &exitErr) {
        // CombinedOutput is embedded in the message; surface dolt's own stderr to the user
        return fmt.Errorf("dolt init failed; see dolt output above; check dolt version compatibility")
    }
    return err
}

When it happens

Trigger: ensureDoltInit finds no .dolt/ directory and runs exec.Command("dolt", "init") in doltDir; it fails when the dolt binary is missing from PATH, too old/incompatible, or dolt init itself rejects the directory (corrupt parent, permissions, another dolt process holding it).

Common situations: Dolt not installed or not on PATH in CI/containers after bd upgrade to server-only mode; dolt binary version mismatch with the database format; running inside a container without the dolt executable; dolt init reporting an existing/incompatible repository.

Related errors

• failed to initialize remote cache: %w
• dry-run parent lookup requires an existing cached remote sto
• failed to open target store for dry-run: %w
• %w. Hint: run 'bd init' to create a database in the current
• invalid --dolt-auto-commit=%q (valid: off, on, batch)

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