{"record":{"id":"c621e2177dbea300","repo":"gastownhall/beads","slug":"failed-to-read-template-s-w","errorCode":null,"errorMessage":"failed to read template %s: %w","messagePattern":"failed to read template (.+?): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/bd/init_agent.go","lineNumber":48,"sourceCode":"}\n\n// updateAgentFile creates or updates an agent instructions file with embedded template content.\n// When a beads section already exists (legacy or current), it is updated to the latest\n// versioned format so that `bd init` never silently locks in stale sections.\n// If the file already has a full profile and a minimal profile is requested, the full\n// profile is preserved to avoid information loss.\nfunc updateAgentFile(filename string, verbose bool, templatePath string, profile agents.Profile, opts agents.RenderOpts) error {\n\t// Check if file exists\n\t//nolint:gosec // G304: filename validated by config.ValidateAgentsFile or defaulted to AGENTS.md\n\tcontent, err := os.ReadFile(filename)\n\tif os.IsNotExist(err) {\n\t\t// File doesn't exist - create from template\n\t\tvar newContent string\n\t\tif templatePath != \"\" {\n\t\t\t//nolint:gosec // G304: templatePath comes from --agents-template flag\n\t\t\tdata, readErr := os.ReadFile(templatePath)\n\t\t\tif readErr != nil {\n\t\t\t\treturn fmt.Errorf(\"failed to read template %s: %w\", templatePath, readErr)\n\t\t\t}\n\t\t\tnewContent = string(data)\n\t\t} else {\n\t\t\tnewContent = agents.EmbeddedDefault()\n\t\t}\n\n\t\t// Replace the beads section with the requested profile.\n\t\t// EmbeddedDefault() ships with profile:full; swap to the requested profile\n\t\t// (which defaults to minimal). Also handles legacy markers without profile metadata.\n\t\tif strings.Contains(newContent, \"BEGIN BEADS INTEGRATION\") {\n\t\t\tif replaced, changed, err := agents.ReplaceSectionWithOpts(newContent, profile, opts); err == nil && changed {\n\t\t\t\tnewContent = replaced\n\t\t\t}\n\t\t}\n\n\t\t// #nosec G306 - markdown needs to be readable\n\t\tif err := os.WriteFile(filename, []byte(newContent), 0644); err != nil {\n\t\t\treturn fmt.Errorf(\"failed to create %s: %w\", filename, err)","sourceCodeStart":30,"sourceCodeEnd":66,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/init_agent.go#L30-L66","documentation":"updateAgentFile builds new agent-instruction files from a template. When the target file doesn't exist and --agents-template is set, it reads that template file; a read failure (missing file, bad permissions) is wrapped here and aborts creating the agent file. Without a template flag, the embedded default (agents.EmbeddedDefault) is used instead.","triggerScenarios":"bd init (or addAgentsInstructions) run with --agents-template pointing to a nonexistent or unreadable path, in a repo where the target agent markdown (e.g. AGENTS.md) does not yet exist.","commonSituations":"Typo in --agents-template path; template lives outside the sandbox's allowed mounts; relative path resolved from an unexpected working directory; unreadable permissions on the template.","solutions":["Verify the --agents-template path exists and is readable (ls -l / cat the file)","Use an absolute path for --agents-template","Omit --agents-template to use the built-in embedded default template","Check file permissions on the template and working directory"],"exampleFix":"// before\nbd init --agents-template ./templates/agents.tmpl  # file missing\n// after\nbd init --agents-template /abs/path/templates/agents.tmpl\n# or drop the flag entirely:\nbd init","handlingStrategy":"validation","validationCode":"if [ -n \"$TEMPLATE\" ] && [ ! -r \"$TEMPLATE\" ]; then echo \"template unreadable: $TEMPLATE\" >&2; exit 1; fi","typeGuard":null,"tryCatchPattern":"if err := addAgentsInstructions(...); err != nil && strings.Contains(err.Error(), \"failed to read template\") { /* fix path or drop --agents-template */ }","preventionTips":["Verify template paths with an absolute path","Test `cat <template>` before passing it to --agents-template","Use the embedded default when a custom template isn't required","Mount templates read-accessibly in containers"],"tags":["filesystem","template","agents","init"],"backgroundTag":"template-file-not-found","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}