gastownhall/beads · error

failed to create %s: %w

Error message

failed to create %s: %w

What it means

updateAgentFile writes the new agent markdown (template content or embedded default) with os.WriteFile at mode 0644 when the target file does not exist. A write failure is wrapped here, meaning the agent instruction file could not be created — typically a filesystem permission or path problem.

Source

Thrown at cmd/bd/init_agent.go:66

				return fmt.Errorf("failed to read template %s: %w", templatePath, readErr)
			}
			newContent = string(data)
		} else {
			newContent = agents.EmbeddedDefault()
		}

		// Replace the beads section with the requested profile.
		// EmbeddedDefault() ships with profile:full; swap to the requested profile
		// (which defaults to minimal). Also handles legacy markers without profile metadata.
		if strings.Contains(newContent, "BEGIN BEADS INTEGRATION") {
			if replaced, changed, err := agents.ReplaceSectionWithOpts(newContent, profile, opts); err == nil && changed {
				newContent = replaced
			}
		}

		// #nosec G306 - markdown needs to be readable
		if err := os.WriteFile(filename, []byte(newContent), 0644); err != nil {
			return fmt.Errorf("failed to create %s: %w", filename, err)
		}
		if verbose {
			fmt.Printf("  %s Created %s with agent instructions\n", ui.RenderPass("✓"), filename)
		}
		return nil
	} else if err != nil {
		return fmt.Errorf("failed to read %s: %w", filename, err)
	}

	// 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 {

View on GitHub (pinned to 71377f2769)

Solutions

1. Check directory write permissions and fix with chmod/chown
2. Run bd init as the user who owns the repo working tree
3. Free disk space if the disk is full
4. Check for sandbox/SELinux denials in audit logs and allow writes to the repo

Example fix

// before: read-only workspace
$ bd init
failed to create AGENTS.md: permission denied
// after
$ chmod u+w . && bd init
# or in CI, ensure the workspace is writable:
chmod -R u+w "$GITHUB_WORKSPACE"

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

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

When it happens

Trigger: Creating AGENTS.md (or similar) during bd init/addAgentsInstructions when the target directory is read-only, owned by another user, or the path is otherwise unwritable.

Common situations: Read-only repo checkout or CI workspace; running bd init as a different user than the repo owner; disk full; SELinux/AppArmor denials; immutable files.

Related errors

• failed to read %s: %w
• failed to update %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/c29ebcf63f55710f. Report an issue: GitHub.