gastownhall/beads · error

loading config for gate resolution: %w

Error message

loading config for gate resolution: %w

What it means

ResolvePhysicalRoots wraps configfile.Load(abs) failures as "loading config for gate resolution: %w". A present metadata.json (configfile.ConfigPath) is treated as authoritative: if it exists but cannot be parsed or loaded, gate planning refuses to guess or fall back — matching the open path's behavior of never silently falling back on broken metadata. This surfaces corrupted or hand-edited metadata.json files early.

Source

Thrown at internal/doltserver/physical_root.go:263

// file's parent itself (and refuses symlinked roots), and resolving here too
// would double-handle and could disagree with the gate's own rules.
func ResolvePhysicalRoots(beadsDir string) (PhysicalRoots, error) {
	abs, err := filepath.Abs(beadsDir)
	if err != nil {
		return PhysicalRoots{}, fmt.Errorf("resolving beads dir %s: %w", beadsDir, err)
	}
	abs = filepath.Clean(abs)
	pr := PhysicalRoots{BeadsDir: abs}

	// Side-effect-free config load: never trigger the legacy config.json
	// migration. Absent metadata.json is treated as cfg == nil.
	var cfg *configfile.Config
	if _, statErr := os.Stat(configfile.ConfigPath(abs)); statErr == nil {
		loaded, loadErr := configfile.Load(abs)
		if loadErr != nil {
			// A present-but-broken metadata.json is authoritative: the open
			// path refuses to fall back, so gate planning refuses to guess.
			return PhysicalRoots{}, fmt.Errorf("loading config for gate resolution: %w", loadErr)
		}
		cfg = loaded
	}

	addRoot := func(root string) error {
		rootAbs, aerr := filepath.Abs(root)
		if aerr != nil {
			return fmt.Errorf("resolving physical root %s: %w", root, aerr)
		}
		pr.Roots = append(pr.Roots, filepath.Clean(rootAbs))
		return nil
	}

	switch {
	case cfg != nil && cfg.IsDoltProxiedServerMode():
		pr.Mode = "proxied-server"
		root, perr := ResolveProxiedServerRootPath(abs)
		if perr != nil {

View on GitHub (pinned to 71377f2769)

Solutions

1. Open .beads/metadata.json in a JSON linter (jq . metadata.json) and fix the syntax/type error.
2. If the file is truncated, restore it from git history or a backup; otherwise delete it and let bd recreate defaults (losing server metadata like PID/port).
3. Check for concurrent writers: ensure no other bd process was mid-write; re-run after it exits.
4. Validate with the same bd version that wrote the file; upgrade bd if the schema is newer.

Example fix

// before
$ cat .beads/metadata.json
{"serverPid": 1234, "port": }        // truncated
// after
$ bd doctor   # or fix manually
$ vi .beads/metadata.json
{"serverPid": 1234, "port": 8123}
$ bd start

path := configfile.ConfigPath(abs)
if data, err := os.ReadFile(path); err == nil {
    var v map[string]any
    if err := json.Unmarshal(data, &v); err != nil {
        return fmt.Errorf("metadata.json is not valid JSON: %v", err)
    }
}

func metadataParses(path string) bool {
    data, err := os.ReadFile(path)
    if err != nil { return false }
    var v map[string]any
    return json.Unmarshal(data, &v) == nil
}

roots, err := ResolvePhysicalRoots(beadsDir)
if err != nil {
    if strings.Contains(err.Error(), "loading config for gate resolution") {
        return fmt.Errorf("%s is corrupt; restore from backup or delete to regenerate", configfile.ConfigPath(abs))
    }
    return err
}

When it happens

Trigger: ResolvePhysicalRoots finds configfile.ConfigPath(abs) exists, calls configfile.Load, and load fails: invalid JSON, wrong types after manual editing, truncated file from a crash/partial write, or a schema version the current code cannot read.

Common situations: User hand-edited .beads/metadata.json and introduced a JSON syntax error; an interrupted bd process left a truncated metadata.json; an older/newer bd wrote a field type the current version rejects.

Related errors

• ExternalDoltConfig: must set Socket or (Host, Port)
• metadata.repo: %w
• metadata.repo must not be null
• invalid metadata: %w
• invalid metadata: %w

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