gastownhall/beads · error

writing dolt compatibility marker %s: %w

Error message

writing dolt compatibility marker %s: %w

What it means

Returned by MarkDoltDirCompatible when os.WriteFile fails to create the .bd-dolt-ok compatibility marker inside the dolt database directory. The marker records that the repository was created/acknowledged by bd 0.56+ (server-mode compatible); without it, bd may later treat the database as a pre-0.56 legacy database. The wrapped error comes from the filesystem (permissions, full disk, etc.).

Source

Thrown at internal/doltserver/doltserver.go:1921

		return errors.New("dolt directory is required")
	}
	dotDolt := filepath.Join(doltDir, ".dolt")
	if info, err := os.Stat(dotDolt); err != nil {
		if os.IsNotExist(err) {
			return nil
		}
		return fmt.Errorf("checking dolt metadata directory %s: %w", dotDolt, err)
	} else if !info.IsDir() {
		return fmt.Errorf("dolt metadata path %s is not a directory", dotDolt)
	}
	markerPath := filepath.Join(doltDir, bdDoltMarker)
	if _, err := os.Stat(markerPath); err == nil {
		return nil
	} else if !os.IsNotExist(err) {
		return fmt.Errorf("checking dolt compatibility marker %s: %w", markerPath, err)
	}
	if err := os.WriteFile(markerPath, []byte("ok\n"), 0600); err != nil {
		return fmt.Errorf("writing dolt compatibility marker %s: %w", markerPath, err)
	}
	return nil
}

// ensureDoltInit initializes a dolt database directory if .dolt/ doesn't exist.
// If .dolt/ exists, seeds the .bd-dolt-ok marker for existing working databases.
// See GH#2137 for background on pre-0.56 database compatibility.
func ensureDoltInit(doltDir string) error {
	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

View on GitHub (pinned to 71377f2769)

Solutions

1. Fix permissions on the dolt directory (and any existing marker file) so the current user can write, e.g. chown -R $(whoami) .beads
2. If a non-writable .bd-dolt-ok file exists, remove it: rm .beads/.bd-dolt-ok (it will be recreated with mode 0600)
3. Check that the filesystem containing doltDir is not full or mounted read-only (df -h, mount | grep ro) and free space or remount
4. Re-run the bd command; MarkDoltDirCompatible is retried defensively on future runs

Example fix

// before (shell, database owned by root)
$ bd ready
# error: writing dolt compatibility marker /path/.beads/.bd-dolt-ok: open ...: permission denied
// after
$ sudo chown -R $(whoami) /path/.beads
$ bd ready

markerPath := filepath.Join(doltDir, ".bd-dolt-ok")
if info, err := os.Stat(doltDir); err != nil || !info.IsDir() {
    return fmt.Errorf("dolt dir %s missing or not a directory", doltDir)
}
if f, err := os.OpenFile(markerPath, os.O_WRONLY|os.O_CREATE, 0600); err != nil {
    return fmt.Errorf("marker %s not writable: %w", markerPath, err)
} else {
    f.Close()
}

if err := MarkDoltDirCompatible(doltDir); err != nil {
    var pathErr *fs.PathError
    if errors.As(err, &pathErr) && errors.Is(pathErr, os.ErrPermission) {
        // advise: chown/chmod doltDir for current user
    }
    return err
}

When it happens

Trigger: Calling MarkDoltDirCompatible (directly or via ensureDoltInit after a successful 'dolt init') on a doltDir whose parent directory is not writable by the current user, where a file named .bd-dolt-ok already exists as a read-only/non-writable regular file, or on a full read-only filesystem.

Common situations: Running bd under a different user than the one that created .beads (e.g. sudo vs. local user); .beads mounted read-only or on a full disk; an admin manually created a non-writable .bd-dolt-ok file; container volume with wrong ownership.

Related errors

• dolt path is not executable
• creating .bd-dolt-ok marker: %w
• failed to remove Dolt database: %w
• inspecting remote target %s: %w
• reading remote store %s: %w

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