gastownhall/beads · critical

loading storage metadata: %w

Error message

loading storage metadata: %w

What it means

The no-CGO build of OpenBestAvailable wraps configfile.Load failures identically to the CGO build: 'loading storage metadata: %w'. The storage metadata file in .beads could not be loaded, so backend selection cannot proceed. The root cause (missing/unreadable/corrupt metadata) is always available via the wrapped error.

Source

Thrown at beads_nocgo.go:22

import (
	"context"
	"fmt"

	"github.com/steveyegge/beads/internal/configfile"
	"github.com/steveyegge/beads/internal/storage/backends"
	"github.com/steveyegge/beads/internal/storage/dolt"
)

// OpenBestAvailable opens a beads database using the best available backend
// for the given .beads directory. In non-CGO builds, only Dolt server mode is
// supported; embedded Dolt returns an error directing the user to server mode.
//
// beadsDir is the path to the .beads directory.
func OpenBestAvailable(ctx context.Context, beadsDir string) (Storage, error) {
	cfg, err := configfile.Load(beadsDir)
	if err != nil {
		return nil, fmt.Errorf("loading storage metadata: %w", err)
	}
	if cfg == nil {
		cfg = configfile.DefaultConfig()
	}
	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 {

View on GitHub (pinned to 71377f2769)

Solutions

1. Read the wrapped cause to distinguish parse vs IO errors
2. Regenerate metadata with bd init or restore it from version control
3. Verify the process can read the .beads directory (permissions, mount flags)

Example fix

// before
store, err := beads.OpenBestAvailable(ctx, ".beads")
// after
store, err := beads.OpenBestAvailable(ctx, ".beads")
if err != nil {
    log.Fatalf("cannot load .beads metadata: %v", err) // includes wrapped cause
}

if _, err := os.Stat(filepath.Join(beadsDir)); err != nil {
    return fmt.Errorf("beads dir missing; run bd init: %w", err)
}

store, err := beads.OpenBestAvailable(ctx, dir)
if err != nil {
    log.Fatalf("storage metadata load failed: %v", err)
}

When it happens

Trigger: Calling OpenBestAvailable(ctx, beadsDir) in a pure-Go (CGO_ENABLED=0) build when configfile.Load on the .beads directory metadata returns an error.

Common situations: Deploying the pure-Go bd binary against a .beads directory created by another tool; truncated or hand-edited metadata file; read-only mounts or permission-denied after containerization.

Related errors

• loading storage metadata: %w
• no store is open for this workspace
• not found
• db: ChildCounterSQLRepository.NextChildID: parentID must not
• db: DependencySQLRepository.Insert: dep must not be nil

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