gastownhall/beads · error

no metadata.json found

Error message

no metadata.json found

What it means

DatabaseConfig errors when .beads/metadata.json does not exist (configfile.Load returns nil, nil). The DatabaseConfig fix reconciles the configured database name against local .db files, so it cannot run in a workspace without metadata.

Source

Thrown at cmd/bd/doctor/fix/database_config.go:28

// DatabaseConfig auto-detects and fixes metadata.json database config mismatches.
// This fix only applies to SQLite backends where .db files on disk may not match
// the configured database name. Dolt backends store data on a server, so there
// are no local .db files to reconcile.
func DatabaseConfig(path string) error {
	beadsDir, err := resolvedWorkspaceBeadsDir(path)
	if err != nil {
		return err
	}

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

	// Dolt backend stores data on the server — no local .db files to reconcile
	if cfg.GetBackend() == configfile.BackendDolt {
		return fmt.Errorf("database config fix not applicable for Dolt backend (data is on the server)")
	}

	fixed := false

	// Check if configured database name matches the actual .db file on disk
	actualDB := findActualDBFile(beadsDir)
	if actualDB != "" && cfg.Database != actualDB {
		fmt.Printf("  Updating database: %s → %s\n", cfg.Database, actualDB)
		cfg.Database = actualDB
		fixed = true
	}

	if !fixed {

View on GitHub (pinned to 71377f2769)

Solutions

1. Run `bd init` in the project root to create .beads/metadata.json
2. Confirm you are in the intended repository (ls .beads/ should show metadata.json)
3. Check and fix .beads/redirect if it points to a nonexistent directory
4. Restore metadata.json from git history or a backup if it was accidentally removed

Example fix

// shell
$ ls .beads/metadata.json   # not found
$ bd init
$ bd doctor fix

if _, err := os.Stat(filepath.Join(beadsDir, "metadata.json")); os.IsNotExist(err) {
    return fmt.Errorf("workspace not initialized: run 'bd init'")
}

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

if err := fix.DatabaseConfig(path); err != nil {
    if err.Error() == "no metadata.json found" {
        // initialize workspace or correct the path
    }
    return err
}

When it happens

Trigger: Invoking DatabaseConfig in a directory whose resolved .beads dir lacks metadata.json: bd never initialized there, wrong working directory, or .beads/redirect pointing at an empty/stale location.

Common situations: Running doctor fixes in a brand-new clone before `bd init`; pointing bd at a repo without beads metadata; a moved workspace whose redirect is stale.

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/4034e4cea82102d2. Report an issue: GitHub.