gastownhall/beads · error

failed to update %s: %w

Error message

failed to update %s: %w

What it means

After ReplaceSectionWithOpts reports changes, updateAgentFile writes the updated file back with os.WriteFile (mode 0644). A write failure is wrapped here, meaning the beads section was computed as changed but the updated markdown could not be persisted to disk.

Source

Thrown at cmd/bd/init_agent.go:99

		// 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") {
		newContent += "\n"
	}

	newContent += "\n" + agents.RenderSectionWithOpts(profile, opts)

View on GitHub (pinned to 71377f2769)

Solutions

1. Check and fix write permissions on the file (chmod/chown)
2. Ensure the working tree is writable before running bd init
3. Free disk space / raise quota if the disk is full
4. Check chattr +i or sandbox policies blocking writes and remove the restriction

Example fix

// before: read-only checkout
$ bd init
failed to update AGENTS.md: read-only file system
// after
$ chmod -R u+w . && bd init

[ -w AGENTS.md ] || { echo "AGENTS.md not writable" >&2; exit 1; }

if err := addAgentsInstructions(...); err != nil && strings.Contains(err.Error(), "failed to update ") { log.Fatalf("cannot persist updated agent file: %v", err) }

When it happens

Trigger: Updating an existing agent markdown whose beads section changed, but the file/directory is unwritable at write time (permissions changed between read and write, read-only mount, disk full).

Common situations: CI workspaces made read-only after checkout; another process holding the file or flipping permissions; disk quota exceeded; immutable bit set on the file.

Related errors

• failed to create %s: %w
• failed to read %s: %w
• failed to create .beads directory: %v Permission denied. Ch
• failed to create .beads directory: %w
• failed to set beads.role config: %w

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