embedded Dolt requires CGO; use server mode (bd init --serve

Error message

embedded Dolt requires CGO; use server mode (bd init --server)

What it means

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.

Source

Thrown at beads_nocgo.go:45

	if !configfile.IsSupportedBackend(cfg.Backend) {
		return nil, configuredBackendUnavailable(cfg.Backend)
	}

	// Dispatch to a registered extension backend before any Dolt path, mirroring
	// the CLI store factories so SDK callers get the backend they registered
	// instead of the embedded-Dolt-requires-CGO error.
	if backend, ok := backends.Lookup(cfg.GetBackend()); ok {
		return backend.Open(ctx, beadsDir)
	}

	if cfg.IsDoltServerMode() {
		store, err := dolt.NewFromConfig(ctx, beadsDir)
		if err != nil {
			return nil, err
		}
		return store, nil
	}
	return nil, fmt.Errorf("embedded Dolt requires CGO; use server mode (bd init --server)")
}

View on GitHub (pinned to 71377f2769)

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

Example fix

// before (nocgo build)
bd ready
// after
bd init --server   # or rebuild with CGO_ENABLED=1 go build ./cmd/bd

Defensive patterns

Strategy: fallback

Validate before calling

// detect embedded backend config before opening
if cfg, _ := configfile.Load(beadsDir); cfg != nil && cfg.Backend == "dolt" && !cgoEnabled {
    return errors.New("embedded dolt configured but binary lacks CGO; use --server")
}

Try / catch

store, err := beads.OpenBestAvailable(ctx, dir)
if err != nil && strings.Contains(err.Error(), "requires CGO") {
    return switchToServerMode(dir)
}

Prevention

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

When it happens

Trigger: OpenBestAvailable (beads_nocgo.go) encounters cfg.Backend set to embedded Dolt (e.g. 'dolt' local backend) in the .beads storage metadata.

Common situations: 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.

Related errors

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