{"record":{"id":"03505bc9bf680142","repo":"gastownhall/beads","slug":"open-embedded-engine-for-clone-w","errorCode":null,"errorMessage":"open embedded engine for clone: %w","messagePattern":"open embedded engine for clone: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/bd/bootstrap.go","lineNumber":932,"sourceCode":"\tswitch doltserver.ResolveServerMode(beadsDir) {\n\tcase doltserver.ServerModeEmbedded:\n\t\treturn remoteCloneEmbedded\n\tcase doltserver.ServerModeExternal:\n\t\treturn remoteCloneExternalServer\n\tdefault:\n\t\treturn remoteCloneCLI\n\t}\n}\n\n// cloneViaEmbedded clones using the embedded Dolt engine (CGO required).\nfunc cloneViaEmbedded(ctx context.Context, beadsDir, remoteURL, dbName string) error {\n\tdataDir := filepath.Join(beadsDir, \"embeddeddolt\")\n\tif err := os.MkdirAll(dataDir, 0o750); err != nil {\n\t\treturn fmt.Errorf(\"create embeddeddolt directory: %w\", err)\n\t}\n\tdb, cleanup, err := embeddeddolt.OpenSQL(ctx, dataDir, \"\", \"\")\n\tif err != nil {\n\t\treturn fmt.Errorf(\"open embedded engine for clone: %w\", err)\n\t}\n\tdefer func() { _ = cleanup() }()\n\n\tif err := versioncontrolops.DoltClone(ctx, db, remoteURL, dbName, os.Getenv(\"DOLT_REMOTE_USER\")); err != nil {\n\t\treturn fmt.Errorf(\"clone from remote: %w\", err)\n\t}\n\tfmt.Fprintf(os.Stderr, \"Synced database from %s\\n\", remoteURL)\n\treturn nil\n}\n\n// cloneViaServer clones by connecting to the external Dolt server and\n// executing CALL DOLT_CLONE. The server places the database in its own\n// data directory, which is the correct behavior for externally managed\n// servers where bd does not know the filesystem layout.\nfunc cloneViaServer(ctx context.Context, beadsDir, remoteURL, dbName string, cfg *configfile.Config) error {\n\tport := serverClonePort(beadsDir, cfg)\n\tdsn := doltutil.ServerDSN{\n\t\tSocket:   cfg.GetDoltServerSocket(),","sourceCodeStart":914,"sourceCodeEnd":950,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/bootstrap.go#L914-L950","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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"],"exampleFix":"// before: binary built with CGO disabled\n$ bd bootstrap\n// error: open embedded engine for clone: cgo required\n// after\n$ CGO_ENABLED=1 go install github.com/.../cmd/bd@latest\n$ rm -rf .beads/embeddeddolt && bd bootstrap","handlingStrategy":"fallback","validationCode":"// embedded engine requires CGO builds\nif os.Getenv(\"CGO_ENABLED\") == \"0\" {\n\t// choose server or CLI clone mode instead of embedded\n}","typeGuard":null,"tryCatchPattern":"err := cloneViaEmbedded(ctx, dir, url, db)\nif err != nil {\n\tif strings.Contains(err.Error(), \"open embedded engine\") {\n\t\t// fall back: rm -rf .beads/embeddeddolt, or switch dolt_mode to server and retry via dolt sql-server\n\t}\n}","preventionTips":["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"],"tags":["cgo","embedded-dolt","engine-startup"],"backgroundTag":"embedded-engine-open-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}