gastownhall/beads · error

create embeddeddolt directory: %w

Error message

create embeddeddolt directory: %w

What it means

Wrapped by cloneViaEmbedded in cmd/bd/bootstrap.go:928 when os.MkdirAll fails to create <beadsDir>/embeddeddolt (mode 0750), the data directory for the embedded Dolt engine. The clone cannot proceed without this directory. The wrapped error is an OS-level mkdir failure.

Source

Thrown at cmd/bd/bootstrap.go:928

		}
		return remoteCloneEmbedded
	}

	switch doltserver.ResolveServerMode(beadsDir) {
	case doltserver.ServerModeEmbedded:
		return remoteCloneEmbedded
	case doltserver.ServerModeExternal:
		return remoteCloneExternalServer
	default:
		return remoteCloneCLI
	}
}

// cloneViaEmbedded clones using the embedded Dolt engine (CGO required).
func cloneViaEmbedded(ctx context.Context, beadsDir, remoteURL, dbName string) error {
	dataDir := filepath.Join(beadsDir, "embeddeddolt")
	if err := os.MkdirAll(dataDir, 0o750); err != nil {
		return fmt.Errorf("create embeddeddolt directory: %w", err)
	}
	db, cleanup, err := embeddeddolt.OpenSQL(ctx, dataDir, "", "")
	if err != nil {
		return fmt.Errorf("open embedded engine for clone: %w", err)
	}
	defer func() { _ = cleanup() }()

	if err := versioncontrolops.DoltClone(ctx, db, remoteURL, dbName, os.Getenv("DOLT_REMOTE_USER")); err != nil {
		return fmt.Errorf("clone from remote: %w", err)
	}
	fmt.Fprintf(os.Stderr, "Synced database from %s\n", remoteURL)
	return nil
}

// cloneViaServer clones by connecting to the external Dolt server and
// executing CALL DOLT_CLONE. The server places the database in its own
// data directory, which is the correct behavior for externally managed
// servers where bd does not know the filesystem layout.

View on GitHub (pinned to 71377f2769)

Solutions

1. Check whether .beads/embeddeddolt is a file and remove it (rm -f .beads/embeddeddolt)
2. Fix permissions on the .beads directory so the current user can create directories
3. Ensure the filesystem is writable and has free space
4. Re-run bd init/bd bootstrap

Example fix

// before
$ bd init --remote https://doltremoteapi.dolthub.com/org/beads
// error: create embeddeddolt directory: not a directory
$ file .beads/embeddeddolt   # shows a regular file
// after
$ rm -f .beads/embeddeddolt
$ bd init --remote ...

import "os"
func canCreateDir(beadsDir string) error {
	if fi, err := os.Stat(beadsDir + "/embeddeddolt"); err == nil && !fi.IsDir() {
		return fmt.Errorf("%s/embeddeddolt is a file", beadsDir)
	}
	return os.MkdirTemp(beadsDir, ".wtest") != nil // probe writability via MkdirTemp then remove
}

if err := clone(); err != nil {
	var pe *fs.PathError
	if errors.As(err, &pe) && strings.Contains(err.Error(), "embeddeddolt") {
		// remove stray file and retry
	}
}

When it happens

Trigger: bd init/bootstrap resolves to embedded clone mode and calls cloneViaEmbedded; MkdirAll fails because a file named embeddeddolt already exists in .beads, the parent directory is not writable, or the path is on a read-only filesystem.

Common situations: A stray embeddeddolt file from a previous corrupted run; cloning into a shared/locked directory; read-only CI workspace; full disk.

Related errors

• failed to create planning repo: %w
• ensureProxiedServerConfig: mkdir %s: %w
• newExternalProxiedServerUOWProvider: mkdir %s: %w
• cannot create shared server directory %s: %w
• cannot create shared dolt directory %s: %w

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