gastownhall/beads · error

failed to configure hydration: %w

Error message

failed to configure hydration: %w

What it means

Wraps an error from config.AddRepo(configPath, planningPath) when adding the planning repo to repos.additional for multi-repo hydration. Errors containing 'already exists' are treated as non-fatal and swallowed; any other failure (unreadable/unwritable config.yaml, malformed YAML, I/O error) is wrapped and returned.

Source

Thrown at cmd/bd/init_contributor.go:231

		return fmt.Errorf("failed to set routing contributor path: %w", err)
	}

	fmt.Printf("%s Auto-routing enabled\n", ui.RenderPass("✓"))

	// Step 4b: Enable multi-repo hydration so routed issues are visible (bd-fix-routing)
	fmt.Printf("\n%s Configuring multi-repo hydration...\n", ui.RenderAccent("▶"))

	// Find config.yaml path
	configPath, err := config.FindConfigYAMLPath()
	if err != nil {
		return fmt.Errorf("failed to find config.yaml: %w", err)
	}

	// Add planning repo to repos.additional for hydration
	if err := config.AddRepo(configPath, planningPath); err != nil {
		// Check if already added (non-fatal)
		if !strings.Contains(err.Error(), "already exists") {
			return fmt.Errorf("failed to configure hydration: %w", err)
		}
	}

	fmt.Printf("%s Hydration enabled for planning repo\n", ui.RenderPass("✓"))
	fmt.Println("  Issues from planning repo will appear in 'bd list'")

	// If this is a fork, configure sync to pull beads from upstream (bd-bx9)
	// This ensures `bd dolt pull` gets the latest issues from the source repo,
	// not from the fork's potentially outdated origin/main
	if isFork {
		if err := store.SetConfig(ctx, "sync.remote", "upstream"); err != nil {
			return fmt.Errorf("failed to set sync remote: %w", err)
		}
		fmt.Printf("%s Sync configured to pull from upstream (source repo)\n", ui.RenderPass("✓"))
	}

	// Step 5: Summary
	fmt.Printf("\n%s %s\n\n", ui.RenderPass("✓"), ui.RenderBold("Contributor setup complete!"))

View on GitHub (pinned to 71377f2769)

Solutions

1. Validate/fix the YAML in the config.yaml reported by the wrapped error (bd doctor or a YAML linter)
2. Fix file permissions (e.g. chown back to your user if a sudo run changed ownership)
3. Back up and regenerate config.yaml (bd init) if the schema is outdated
4. Retry bd init --contributor after the config file is valid and writable

Example fix

// before — config.yaml with broken indentation
repos:
additional:
  - ~/.beads-planning
// after
repos:
  additional:
    - ~/.beads-planning

// Validate config.yaml parses before adding repos
data, err := os.ReadFile(configPath)
if err == nil {
	var cfg map[string]any
	if err := yaml.Unmarshal(data, &cfg); err != nil {
		return fmt.Errorf("config.yaml is invalid YAML, fix before setup: %w", err)
	}
}

if err := runContributorWizard(ctx, store, ...); err != nil {
	if strings.Contains(err.Error(), "failed to configure hydration") && !strings.Contains(err.Error(), "already exists") {
		fmt.Fprintln(os.Stderr, "Check config.yaml validity and permissions, then retry")
	}
	return err
}

When it happens

Trigger: config.AddRepo fails with a non-'already exists' error inside runContributorWizard — e.g. config.yaml is unreadable, invalid YAML, read-only, or the write-back fails.

Common situations: Hand-edited config.yaml with YAML syntax errors; config.yaml owned by root after a sudo run; disk full; schema drift after a beads version change altered the config format.

Related errors

• failed to set routing mode: %w
• failed to set routing contributor path: %w
• failed to find config.yaml: %w
• server: NewDoltServer: doltBinExec is required
• server: NewDoltServer: rootDir is required

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