What causes "failed to set routing mode: %w" in gastownhall/beads?

Check the wrapped cause printed after the message (e.g. database locked, no such table) and fix that root cause first

failed to set routing mode: %w

Error message

failed to set routing mode: %w

What it means

Wraps an error from store.SetConfig when writing the 'routing.mode' config key during the contributor wizard (bd init --contributor). The beads config store (Dolt-backed) failed to persist the routing mode value 'auto', aborting the wizard setup. The underlying error typically indicates the config store could not be opened or written.

Source

Thrown at cmd/bd/init_contributor.go:210

		cmd = exec.Command("git", "add", ".")
		cmd.Dir = planningPath
		_ = cmd.Run()

		cmd = exec.Command("git", "commit", "-m", "Initial commit: beads planning repository")
		cmd.Dir = planningPath
		_ = cmd.Run()

		fmt.Printf("%s Planning repository created\n", ui.RenderPass("✓"))
	} else {
		fmt.Printf("%s Using existing planning repository\n", ui.RenderPass("✓"))
	}

	// Step 4: Configure contributor routing
	fmt.Printf("\n%s Configuring contributor auto-routing...\n", ui.RenderAccent("▶"))

	// Set routing config (canonical namespace per internal/config/config.go)
	if err := store.SetConfig(ctx, "routing.mode", "auto"); err != nil {
		return fmt.Errorf("failed to set routing mode: %w", err)
	}
	if err := store.SetConfig(ctx, "routing.contributor", planningPath); err != nil {
		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 {

View on GitHub (pinned to 71377f2769)

Solutions

Check the wrapped cause printed after the message (e.g. database locked, no such table) and fix that root cause first
Run bd doctor to verify the .beads Dolt store is healthy, or re-run bd init to (re)initialize the store
Ensure a Dolt server is reachable for server-mode/embedded builds that require it (or rebuild with CGO for embedded mode)
Check filesystem permissions and free space on the directory containing .beads/

Example fix

// before
if err := store.SetConfig(ctx, "routing.mode", "auto"); err != nil {
	return fmt.Errorf("failed to set routing mode: %w", err)
}
// after — verify store health first
if err := store.SetConfig(ctx, "routing.mode", "auto"); err != nil {
	return fmt.Errorf("failed to set routing mode (is the .beads Dolt store initialized/runnable?): %w", err)
}

Defensive patterns

Strategy: try-catch

Validate before calling

// Before running the wizard, verify the store is writable/healthy
if _, err := os.Stat(filepath.Join(repoPath, ".beads")); err != nil {
	return fmt.Errorf("repo not initialized: run bd init first: %w", err)
}

Try / catch

if err := runContributorWizard(ctx, store, ...); err != nil {
	var root error = err
	for errors.Unwrap(root) != nil { root = errors.Unwrap(root) }
	fmt.Fprintf(os.Stderr, "contributor setup failed: %v (cause: %v)\n", err, root)
	os.Exit(1)
}

Prevention

Run bd init before bd init --contributor so the store exists
Run bd doctor periodically to catch store corruption early
Avoid concurrent bd processes against the same .beads directory
Ensure the Dolt server is running for server-mode builds

When it happens

Trigger: store.SetConfig(ctx, "routing.mode", "auto") returns an error inside runContributorWizard — e.g. the Dolt database in .beads/ is corrupt, locked, or unreachable, the store was not initialized, or a Dolt server connection failed.

Common situations: Running bd init --contributor in a repo whose .beads database is missing, not migrated to Dolt, or locked by another process; no-CGO builds without a running Dolt server; disk or permissions problems on .beads/.

Related errors

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