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

Rebuild with CGO_ENABLED=1 and an available C compiler

errNoCGO

errNoCGO

Error message

embeddeddolt: requires CGO (build with CGO_ENABLED=1)

What it means

errNoCGO is the sentinel returned by every embeddeddolt store constructor (Open, OpenReadOnly, OpenForPreviewCommand, OpenForReadOnlyCommand, OpenForWorkingSetReconcile) when the package is compiled without CGO. The embedded Dolt engine requires cgo, so the stub package replaces real constructors with one that always fails with this message.

Source

Thrown at internal/storage/embeddeddolt/store_stub.go:17

//go:build !cgo

package embeddeddolt

import (
	"context"
	"errors"
)

// EmbeddedDoltStore is a stub for builds without CGO.
type EmbeddedDoltStore struct {
	dataDir  string
	database string
	branch   string
}

var errNoCGO = errors.New("embeddeddolt: requires CGO (build with CGO_ENABLED=1)")

// Open returns an error when CGO is not enabled.
func Open(_ context.Context, _, _, _ string) (*EmbeddedDoltStore, error) {
	return nil, errNoCGO
}

// OpenReadOnly returns an error when CGO is not enabled.
func OpenReadOnly(_ context.Context, _, _, _ string) (*EmbeddedDoltStore, error) {
	return nil, errNoCGO
}

// OpenForPreviewCommand returns an error when CGO is not enabled.
func OpenForPreviewCommand(_ context.Context, _, _, _ string) (*EmbeddedDoltStore, error) {
	return nil, errNoCGO
}

// OpenForReadOnlyCommand returns an error when CGO is not enabled.
func OpenForReadOnlyCommand(_ context.Context, _, _, _ string) (*EmbeddedDoltStore, error) {

View on GitHub (pinned to 71377f2769)

Solutions

Rebuild with CGO_ENABLED=1 and an available C compiler
Add gcc/build-essential to the build container
Verify with `go env CGO_ENABLED` that cgo is enabled for the build; fall back to server-mode Dolt if cgo is impossible

Example fix

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

Defensive patterns

Strategy: fallback

Validate before calling

// runtime sentinel check
if errors.Is(err, errNoCGO) || strings.Contains(err.Error(), "requires CGO") { /* fallback */ }

Type guard

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

Try / catch

store, err := embeddeddolt.Open(ctx, dir, db, branch)
if isCGOUnavailable(err) {
    return useServerModeDolt(ctx) // fallback path
}
return err

Prevention

Always build with CGO_ENABLED=1 for embedded mode; pin it in Makefile/CI
Install a C toolchain (gcc/clang) in build containers
Detect cgo availability at startup and warn or fall back to server mode

When it happens

Trigger: Any EmbeddedDoltStore open call in a binary built with CGO_ENABLED=0 — cross-compilation, missing C toolchain, or Docker scratch builds.

Common situations: CI cross-compile jobs (CGO defaults off when cross-compiling); minimal build containers without gcc; GOFLAGS or CGO_ENABLED=0 set in the environment.

Related errors

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