gastownhall/beads · error

persist sync.remote to config.yaml: %w

Error message

persist sync.remote to config.yaml: %w

What it means

Wrapped by finalizeSyncedBootstrap in cmd/bd/bootstrap.go:849 when config.SetYamlConfigInDir fails to persist sync.remote into .beads/config.yaml. This key lets later fresh clones and bootstrap retries rediscover the remote without probing origin refs, so failure to write it leaves the workspace without recorded remote state. The wrapped error is a YAML read/write failure in the .beads directory.

Source

Thrown at cmd/bd/bootstrap.go:849

		cfg.Database = "dolt"
	}

	if err := cfg.Save(beadsDir); err != nil {
		return fmt.Errorf("write metadata.json: %w", err)
	}

	if err := createConfigYaml(beadsDir, false, ""); err != nil {
		return fmt.Errorf("create config.yaml: %w", err)
	}
	if err := doctor.EnsureGitignoreForBeadsDir(beadsDir); err != nil {
		return fmt.Errorf("ensure .beads/.gitignore: %w", err)
	}

	// Persist sync.remote so subsequent fresh clones (and bd bootstrap
	// retries) can rediscover the remote without re-probing origin refs.
	if syncRemote != "" {
		if err := config.SetYamlConfigInDir(beadsDir, "sync.remote", syncRemote); err != nil {
			return fmt.Errorf("persist sync.remote to config.yaml: %w", err)
		}
	}

	return nil
}

type remoteCloneMode int

const (
	remoteCloneAuto remoteCloneMode = iota
	remoteCloneEmbedded
	remoteCloneExternalServer
	remoteCloneCLI
)

// cloneFromRemote clones a Dolt database from a remote URL.
// In embedded mode, uses the embedded engine's DOLT_CLONE procedure.
// In external server mode, connects to the running server via MySQL and

View on GitHub (pinned to 71377f2769)

Solutions

1. Validate/fix YAML syntax in .beads/config.yaml (run a YAML parser over it or restore from git)
2. Fix write permissions on .beads and config.yaml
3. Delete a malformed config.yaml and re-run bd bootstrap (createConfigYaml will recreate it)
4. Upgrade/downgrade bd so the config.yaml version matches what you are running

Example fix

// before: hand-edited config.yaml with a tab character -> yaml parse error
// after
$ bd bootstrap
// error: persist sync.remote to config.yaml: yaml: found character that cannot start any token
$ git checkout -- .beads/config.yaml  # or fix the tab
$ bd bootstrap

// validate config.yaml parses before bootstrap
import "gopkg.in/yaml.v3"
func validYAML(path string) error {
	b, err := os.ReadFile(path)
	if err != nil { return err }
	var m map[string]any
	return yaml.Unmarshal(b, &m)
}

if err := finalize(); err != nil {
	if strings.Contains(err.Error(), "persist sync.remote") {
		// restore config.yaml from git or delete it and re-run bootstrap
	}
}

When it happens

Trigger: bd bootstrap calls finalizeSyncedBootstrap with a non-empty syncRemote and SetYamlConfigInDir fails due to unparseable existing config.yaml, unwritable directory, or config.yaml existing as a directory.

Common situations: A hand-edited config.yaml with invalid YAML syntax; permissions changed by another tool; a version mismatch where config.yaml was written by a newer bd with unsupported syntax.

Related errors

• failed to persist sync.remote to config.yaml: %w
• failed to persist sync.remote to config.yaml: %v
• failed to configure hydration: %w
• error reading config file: %w
• error merging config file %s: %w

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