gastownhall/beads · error

legacy SQLite migration requires CGO

Error message

legacy SQLite migration requires CGO

What it means

The legacy SQLite reader needs CGO to link the SQLite driver. In builds compiled without CGO, a stub Export is compiled that keeps the command available but always fails, telling the user the feature requires a CGO-enabled build.

Source

Thrown at internal/migration/legacysqlite/reader_nocgo.go:13

//go:build !cgo

package legacysqlite

import (
	"context"
	"fmt"
	"io"
)

// Export keeps the command surface available in no-CGO builds.
func Export(context.Context, string, string, io.Writer) error {
	return fmt.Errorf("legacy SQLite migration requires CGO")
}

View on GitHub (pinned to 71377f2769)

Solutions

1. Rebuild with CGO enabled: CGO_ENABLED=1 go build ./cmd/bd (requires gcc and libc dev headers).
2. Use a migration binary built with CGO (official cgo-enabled release) for the one-time legacy migration.
3. If a CGO build is impossible, export the legacy data on another machine with CGO and import the resulting JSONL on this machine.

Example fix

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

if strings.Contains(err.Error(), "requires CGO") {
    // offer JSONL export/import path instead of direct SQLite read
}

if err := legacysqlite.Export(ctx, dbPath, project, w); err != nil {
    if strings.Contains(err.Error(), "requires CGO") {
        return fmt.Errorf("use a CGO-enabled build for legacy migration: %w", err)
    }
    return err
}

When it happens

Trigger: Calling Export (legacy SQLite migration) from a binary built with CGO_ENABLED=0 (e.g. default cross-compiles, distroless/scratch Docker images, or a pure-Go toolchain without a C compiler).

Common situations: Running a statically-linked release binary of bd and trying to migrate an old SQLite-based beads database; CI images built with CGO disabled; musl/alpine builds without gcc.

Related errors

• embeddeddolt: requires CGO (build with CGO_ENABLED=1)
• errNoCGO
• sealed legacy SQLite database does not match source fingerpr
• sealed legacy SQLite WAL does not match source fingerprint
• legacy SQLite source changed while sealing

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