{"record":{"id":"8b2beb4003ccc564","repo":"gastownhall/beads","slug":"loading-storage-metadata-w","errorCode":null,"errorMessage":"loading storage metadata: %w","messagePattern":"loading storage metadata: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"beads_cgo.go","lineNumber":28,"sourceCode":"\t\"github.com/steveyegge/beads/internal/storage/backends\"\n\t\"github.com/steveyegge/beads/internal/storage/dolt\"\n\t\"github.com/steveyegge/beads/internal/storage/embeddeddolt\"\n)\n\n// OpenBestAvailable opens a beads database using the best available backend\n// for the given .beads directory. It reads metadata.json to determine the\n// configured mode:\n//\n//   - Embedded Dolt (default): Opens via the CGo embedded Dolt engine.\n//   - Dolt server: Connects to a dolt sql-server via OpenFromConfig.\n//\n// The returned Storage must be closed when no longer needed.\n//\n// beadsDir is the path to the .beads directory.\nfunc OpenBestAvailable(ctx context.Context, beadsDir string) (Storage, error) {\n\tcfg, err := configfile.Load(beadsDir)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"loading storage metadata: %w\", err)\n\t}\n\tif cfg == nil {\n\t\tcfg = configfile.DefaultConfig()\n\t}\n\tif !configfile.IsSupportedBackend(cfg.Backend) {\n\t\treturn nil, configuredBackendUnavailable(cfg.Backend)\n\t}\n\n\t// Dispatch to a registered extension backend before any Dolt path, mirroring\n\t// the CLI store factories so SDK callers get the backend they registered\n\t// instead of a silently-opened embedded Dolt store.\n\tif backend, ok := backends.Lookup(cfg.GetBackend()); ok {\n\t\treturn backend.Open(ctx, beadsDir)\n\t}\n\n\tif cfg.IsDoltServerMode() {\n\t\tstore, err := dolt.NewFromConfig(ctx, beadsDir)\n\t\tif err != nil {","sourceCodeStart":10,"sourceCodeEnd":46,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/beads_cgo.go#L10-L46","documentation":"In the CGO build of the storage layer, OpenBestAvailable loads the .beads directory's storage metadata via configfile.Load and wraps any failure with 'loading storage metadata: %w'. This means the storage configuration file (e.g. .beads/config.yaml or metadata.yaml) could not be read or parsed, so the backend cannot be selected. The underlying error (permission, missing file, bad YAML) is preserved in the wrap chain.","triggerScenarios":"Calling OpenBestAvailable(ctx, beadsDir) when the .beads directory exists but its storage metadata file is unreadable, corrupt, or fails configfile.Load validation.","commonSituations":"Partially-initialized .beads directory (interrupted bd init); a manually edited or truncated config file; permission problems after copying a repo as another user; a stale metadata file from an older beads version.","solutions":["Inspect the underlying wrapped error (errors.Unwrap or %v output) to see whether it is a parse or IO failure","Run bd init in the repo to regenerate valid storage metadata, or restore the metadata file from git","Fix file permissions on the .beads directory (chown/chmod) if the load failed due to access"],"exampleFix":"// before\nstore, err := beads.OpenBestAvailable(ctx, \".beads\")\nif err != nil { return err }\n// after\nstore, err := beads.OpenBestAvailable(ctx, \".beads\")\nif err != nil {\n    return fmt.Errorf(\"check .beads storage metadata: %w\", err)\n}","handlingStrategy":"validation","validationCode":"if _, err := os.Stat(filepath.Join(beadsDir, \"config.yaml\")); err != nil {\n    return fmt.Errorf(\".beads metadata missing; run bd init first: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"store, err := beads.OpenBestAvailable(ctx, dir)\nif err != nil {\n    return fmt.Errorf(\"loading storage metadata: %w\", err) // inspect wrapped cause\n}","preventionTips":["Always run bd init before programmatic use of a .beads dir","Keep .beads metadata files under version control","Check permissions after copying repos between users/containers"],"tags":["go","storage","config-load","embedded-dolt"],"backgroundTag":"storage-metadata-load-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}