What causes "open embedded engine for clone: %w" in gastownhall/beads?

Rebuild/reinstall bd with CGO_ENABLED=1 (embedded mode requires CGO)

open embedded engine for clone: %w

Error message

open embedded engine for clone: %w

What it means

Wrapped by cloneViaEmbedded in cmd/bd/bootstrap.go:932 when embeddeddolt.OpenSQL fails to open the embedded Dolt SQL engine in the freshly created embeddeddolt data directory. The embedded engine requires CGO and an initialized Dolt environment; failure here means the engine could not start at all, before any remote cloning happens.

Source

Thrown at cmd/bd/bootstrap.go:932

	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.
func cloneViaServer(ctx context.Context, beadsDir, remoteURL, dbName string, cfg *configfile.Config) error {
	port := serverClonePort(beadsDir, cfg)
	dsn := doltutil.ServerDSN{
		Socket:   cfg.GetDoltServerSocket(),

View on GitHub (pinned to 71377f2769)

Solutions

Rebuild/reinstall bd with CGO_ENABLED=1 (embedded mode requires CGO)
Delete .beads/embeddeddolt and re-run so the engine re-initializes a fresh data dir
Check bd/dolt version compatibility notes; align versions
Set dolt_mode=server in metadata.json/config and use a running dolt sql-server instead of embedded mode

Example fix

// before: binary built with CGO disabled
$ bd bootstrap
// error: open embedded engine for clone: cgo required
// after
$ CGO_ENABLED=1 go install github.com/.../cmd/bd@latest
$ rm -rf .beads/embeddeddolt && bd bootstrap

Defensive patterns

Strategy: fallback

Validate before calling

// embedded engine requires CGO builds
if os.Getenv("CGO_ENABLED") == "0" {
	// choose server or CLI clone mode instead of embedded
}

Try / catch

err := cloneViaEmbedded(ctx, dir, url, db)
if err != nil {
	if strings.Contains(err.Error(), "open embedded engine") {
		// fall back: rm -rf .beads/embeddeddolt, or switch dolt_mode to server and retry via dolt sql-server
	}
}

Prevention

Install bd binaries built with CGO_ENABLED=1 if you use embedded mode
After upgrading bd, remove a stale .beads/embeddeddolt directory to avoid storage-version mismatches
Run embedded mode on machines with adequate memory and file-descriptor limits
Prefer server mode in containers/minimal images where embedded libraries may be missing

When it happens

Trigger: cloneViaEmbedded calls OpenSQL and it errors: CGO disabled (CGO_ENABLED=0 build), incompatible GoDolt binary/library, corrupted or version-mismatched embeddeddolt directory, or resource limits (memory/file descriptors).

Common situations: bd binary built without CGO; upgrading bd leaves an embeddeddolt dir from a different Dolt storage version; running in a minimal container lacking required libraries; low memory environments.

Related errors

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