What causes "embeddeddolt: requires CGO (build with CGO_ENABLED=1)" in gastownhall/beads?

Rebuild with CGO_ENABLED=1 (and a working C compiler: gcc/clang)

embeddeddolt: requires CGO (build with CGO_ENABLED=1)

Error message

embeddeddolt: requires CGO (build with CGO_ENABLED=1)

What it means

This is the no-CGO build stub of embeddeddolt.OpenSQL. The embedded Dolt driver is cgo-based; when the binary was compiled with CGO_ENABLED=0 the symbol is replaced by this stub which always errors, telling you to rebuild with CGO enabled.

Source

Thrown at internal/storage/embeddeddolt/open_stub.go:13

//go:build !cgo

package embeddeddolt

import (
	"context"
	"database/sql"
	"errors"
)

// OpenSQL is a stub that returns an error when CGO is not enabled.
func OpenSQL(_ context.Context, _, _, _ string) (*sql.DB, func() error, error) {
	return nil, nil, errors.New("embeddeddolt: requires CGO (build with CGO_ENABLED=1)")
}

View on GitHub (pinned to 71377f2769)

Solutions

Rebuild with CGO_ENABLED=1 (and a working C compiler: gcc/clang)
Install gcc in the build image or use a builder image with the toolchain (e.g. golang images with build-essential)
If CGO cannot be enabled, use the non-embedded (server) Dolt mode instead

Example fix

// before
CGO_ENABLED=0 go build -o bd ./cmd/bd
// after
CGO_ENABLED=1 go build -o bd ./cmd/bd

Defensive patterns

Strategy: fallback

Validate before calling

// build-time check
//go:build cgo
// or at startup:
if strings.Contains(err.Error(), "requires CGO") { /* fall back to server mode */ }

Type guard

func isNoCGOErr(err error) bool {
    return err != nil && strings.Contains(err.Error(), "requires CGO")
}

Try / catch

store, err := embeddeddolt.Open(ctx, dir, db, branch)
if err != nil && isNoCGOErr(err) {
    return openServerModeStore(ctx) // fallback
}
return err

Prevention

Set CGO_ENABLED=1 explicitly in Makefiles and CI build steps
Use builder images with gcc installed
Check `go env CGO_ENABLED` when cross-compiling; cross-compile turns cgo off by default

When it happens

Trigger: Calling embeddeddolt.OpenSQL in a binary built with CGO_ENABLED=0 (default in many cross-compile/scratch-container builds, or via go build without cgo toolchain).

Common situations: Cross-compiling (e.g. GOOS=linux GOARCH=arm64 from a Mac) which disables cgo; distroless/scratch Docker builds; missing C toolchain in CI causing an implicit cgo-less build.

Related errors

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