{"record":{"id":"8b21bf4a61b31b8b","repo":"gastownhall/beads","slug":"embedded-dolt-requires-cgo-use-server-mode-bd-in","errorCode":null,"errorMessage":"embedded Dolt requires CGO; use server mode (bd init --server)","messagePattern":"embedded Dolt requires CGO; use server mode \\(bd init --server\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"beads_nocgo.go","lineNumber":45,"sourceCode":"\tif !configfile.IsSupportedBackend(cfg.Backend) {\n\t\treturn nil, configuredBackendUnavailable(cfg.Backend)\n\t}\n\n\t// Dispatch to a registered extension backend before any Dolt path, mirroring\n\t// the CLI store factories so SDK callers get the backend they registered\n\t// instead of the embedded-Dolt-requires-CGO error.\n\tif backend, ok := backends.Lookup(cfg.GetBackend()); ok {\n\t\treturn backend.Open(ctx, beadsDir)\n\t}\n\n\tif cfg.IsDoltServerMode() {\n\t\tstore, err := dolt.NewFromConfig(ctx, beadsDir)\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t\treturn store, nil\n\t}\n\treturn nil, fmt.Errorf(\"embedded Dolt requires CGO; use server mode (bd init --server)\")\n}\n","sourceCodeStart":27,"sourceCodeEnd":47,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/beads_nocgo.go#L27-L47","documentation":"In the no-CGO build, requesting the embedded Dolt backend is impossible because embedded Dolt requires CGO. OpenBestAvailable detects the embedded backend in its config and returns this error, directing the user to server mode via `bd init --server`. It is a build-configuration incompatibility, not a runtime fault.","triggerScenarios":"OpenBestAvailable (beads_nocgo.go) encounters cfg.Backend set to embedded Dolt (e.g. 'dolt' local backend) in the .beads storage metadata.","commonSituations":"Running the pure-Go bd binary (CGO_ENABLED=0, cross-compiled, or distro build without CGO) against a repo initialized for embedded Dolt; switching from the CGO release binary to a slim Docker image.","solutions":["Re-run with `bd init --server` to migrate the repo to Dolt server mode, and point bd at the server","Install/build the CGO-enabled bd binary (CGO_ENABLED=1 with a C toolchain and Dolt deps)","If you do not need Dolt, switch the configured backend in .beads storage metadata to one supported without CGO"],"exampleFix":"// before (nocgo build)\nbd ready\n// after\nbd init --server   # or rebuild with CGO_ENABLED=1 go build ./cmd/bd","handlingStrategy":"fallback","validationCode":"// detect embedded backend config before opening\nif cfg, _ := configfile.Load(beadsDir); cfg != nil && cfg.Backend == \"dolt\" && !cgoEnabled {\n    return errors.New(\"embedded dolt configured but binary lacks CGO; use --server\")\n}","typeGuard":null,"tryCatchPattern":"store, err := beads.OpenBestAvailable(ctx, dir)\nif err != nil && strings.Contains(err.Error(), \"requires CGO\") {\n    return switchToServerMode(dir)\n}","preventionTips":["Match binary build (CGO vs pure-Go) to the repo's configured backend","Prefer server mode in containers/slim images","Document which bd build your team ships"],"tags":["go","cgo","embedded-dolt","build-config"],"backgroundTag":"backend-not-supported-in-build","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}