gastownhall/beads · error

no metadata.json found

Error message

no metadata.json found

What it means

ConfigValues requires an existing .beads/metadata.json. configfile.Load returns (nil, nil) when the file does not exist, and ConfigValues turns that into this error — the doctor fix has nothing to load or correct without metadata.

Source

Thrown at cmd/bd/doctor/fix/config_values.go:23

	"strings"

	"github.com/steveyegge/beads/internal/configfile"
)

// ConfigValues fixes invalid configuration values in metadata.json.
// Currently handles: database field pointing to SQLite name when backend is Dolt.
func ConfigValues(path string) error {
	beadsDir, err := resolvedWorkspaceBeadsDir(path)
	if err != nil {
		return err
	}

	cfg, err := configfile.Load(beadsDir)
	if err != nil {
		return fmt.Errorf("failed to load config: %w", err)
	}
	if cfg == nil {
		return fmt.Errorf("no metadata.json found")
	}

	fixed := false

	// Fix database field: when backend is Dolt, database should be "dolt" not "beads.db"
	if cfg.GetBackend() == configfile.BackendDolt {
		if strings.HasSuffix(cfg.Database, ".db") || strings.HasSuffix(cfg.Database, ".sqlite") || strings.HasSuffix(cfg.Database, ".sqlite3") {
			fmt.Printf("  Updating database: %q → %q (Dolt backend uses directory)\n", cfg.Database, "dolt")
			cfg.Database = "dolt"
			fixed = true
		}
	}

	if !fixed {
		fmt.Println("  → No configuration issues to fix")
		return nil
	}

View on GitHub (pinned to 71377f2769)

Solutions

1. Run `bd init` in the project root to create .beads/metadata.json
2. Verify you are in the correct repository — check that .beads/metadata.json exists (ls .beads/)
3. Inspect .beads/redirect: if it points to a moved/deleted workspace, correct or remove it
4. Restore metadata.json from backup or version control if it was deleted

Example fix

// shell
$ ls .beads/          # metadata.json missing
$ bd init             # creates .beads/metadata.json
$ bd doctor fix

if _, err := os.Stat(filepath.Join(beadsDir, "metadata.json")); os.IsNotExist(err) {
    return fmt.Errorf("run 'bd init' first: no metadata.json in %s", beadsDir)
}

func hasMetadata(beadsDir string) bool {
    _, err := os.Stat(filepath.Join(beadsDir, "metadata.json"))
    return err == nil
}

if err := fix.ConfigValues(path); err != nil {
    if err.Error() == "no metadata.json found" {
        // run bd init or point at the correct workspace
    }
    return err
}

When it happens

Trigger: Running `bd doctor` fix ConfigValues in a directory whose resolved .beads dir contains no metadata.json — e.g. `bd init` was never run there, or the .beads/redirect points to a workspace initialized without metadata.

Common situations: Running bd doctor in a fresh or wrongly-rooted directory; pointing BD at a repo where only the code exists; the redirect file pointing to a stale location after a workspace move.

Related errors

• no metadata.json found
• server: NewDoltServer: doltBinExec is required
• server: NewDoltServer: rootDir is required
• server: NewDoltServer: configPath is required
• failed to find backup directory: %w

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