gastownhall/beads · error

failed to update beads section in %s: %w

Error message

failed to update beads section in %s: %w

What it means

For an existing agent file, updateAgentFile calls agents.ReplaceSectionWithOpts to rewrite the BEGIN/END BEADS INTEGRATION section into the current versioned format. A failure inside the section replacement logic (marker parsing/rewrite) is wrapped here with the target filename. This is a logic/parse failure, not a filesystem error — the beads markers are malformed or the replacement options are inconsistent.

Source

Thrown at cmd/bd/init_agent.go:94

	// File exists - check if it already has our sections
	contentStr := string(content)
	hasBeads := strings.Contains(contentStr, "BEGIN BEADS INTEGRATION")

	if hasBeads {
		// Preserve existing full profile when minimal is requested (avoid information loss)
		effectiveProfile := profile
		existingMeta := agents.ParseMarker(contentStr[strings.Index(contentStr, "<!-- BEGIN BEADS INTEGRATION"):])
		if existingMeta != nil && existingMeta.Profile == agents.ProfileFull && profile == agents.ProfileMinimal {
			effectiveProfile = agents.ProfileFull
			if verbose {
				fmt.Printf("  ℹ %s already has full profile; preserving (higher-information) content\n", filename)
			}
		}

		// Update existing section to latest versioned format (upgrades legacy markers)
		updated, changed, replaceErr := agents.ReplaceSectionWithOpts(contentStr, effectiveProfile, opts)
		if replaceErr != nil {
			return fmt.Errorf("failed to update beads section in %s: %w", filename, replaceErr)
		}
		if changed {
			// #nosec G306 - markdown needs to be readable
			if err := os.WriteFile(filename, []byte(updated), 0644); err != nil {
				return fmt.Errorf("failed to update %s: %w", filename, err)
			}
			if verbose {
				fmt.Printf("  %s Updated beads section in %s to latest format\n", ui.RenderPass("✓"), filename)
			}
		} else if verbose {
			fmt.Printf("  %s already has current agent instructions\n", filename)
		}
		return nil
	}

	// Append beads section with profile metadata
	newContent := contentStr
	if !strings.HasSuffix(newContent, "\n") {

View on GitHub (pinned to 71377f2769)

Solutions

1. Manually repair the BEGIN/END BEADS INTEGRATION markers in the file (both must be present and intact)
2. Delete the broken beads section and re-run bd init to regenerate a fresh current section
3. Restore the file from git before re-running the update
4. Upgrade bd so legacy markers are handled by the current ReplaceSectionWithOpts version

Example fix

// before: truncated markers in AGENTS.md
<!-- BEGIN BEADS INTEGRATION -->
... (END marker missing)
// after
$ git checkout -- AGENTS.md
$ bd init  # regenerates the section in latest format

grep -c 'BEGIN BEADS INTEGRATION' AGENTS.md | grep -q 1 && grep -q 'END BEADS INTEGRATION' AGENTS.md && echo ok || echo 'malformed beads section'

if err := addAgentsInstructions(...); err != nil && strings.Contains(err.Error(), "failed to update beads section") { /* repair markers or restore file from git, re-run init */ }

When it happens

Trigger: addAgentsInstructions upgrading a legacy or hand-edited beads section in AGENTS.md where ReplaceSectionWithOpts cannot parse or replace the section (e.g. BEGIN marker without matching END, or corrupted markers).

Common situations: Older beads versions with legacy markers; users manually editing inside the managed block and deleting an END marker; conflicting profile options passed via opts.

Related errors

• failed to read template %s: %w
• failed to create %s: %w
• failed to read %s: %w
• failed to update %s: %w
• database is not initialized. Run 'bd init' first

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