What causes "agents file name must not be empty" in gastownhall/beads?

Provide a non-empty filename, e.g. "AGENTS.md", when calling SafeAgentsFile.

agents file name must not be empty

Error message

agents file name must not be empty

What it means

ValidateAgentsFile performs pure string validation of a proposed agents file name before any I/O. An empty string cannot form a valid file path, so it is rejected first. SafeAgentsFile calls this before writing, so an empty name fails fast at the validation layer.

Source

Thrown at internal/config/config.go:1170

// SafeAgentsFile returns the configured agents filename after validation.
// If the stored config value is invalid (e.g. manually edited with traversal
// paths), it falls back to DefaultAgentsFile and logs a warning.
func SafeAgentsFile() string {
	name := AgentsFile()
	if err := ValidateAgentsFile(name); err != nil {
		debug.Logf("config: agents.file %q failed validation (%v), using default", name, err)
		return DefaultAgentsFile
	}
	return name
}

// ValidateAgentsFile checks that filename is safe to use as an agents file path.
// It rejects absolute paths, path separators, names longer than 255 characters,
// and non-markdown extensions. This is a pure string validation function — I/O
// checks (e.g. symlink detection) are deferred to the file write layer.
func ValidateAgentsFile(filename string) error {
	if filename == "" {
		return fmt.Errorf("agents file name must not be empty")
	}
	if len(filename) > 255 {
		return fmt.Errorf("agents file name exceeds 255 characters")
	}
	if strings.ContainsAny(filename, "/\\") {
		return fmt.Errorf("agents file must be a simple filename without path separators, got %q", filename)
	}
	ext := strings.ToLower(filepath.Ext(filename))
	if ext != ".md" {
		return fmt.Errorf("agents file must have .md extension, got %q", ext)
	}
	return nil
}

// getConfigList retrieves a list-typed configuration value from config.yaml,
// accepting either the YAML list form (e.g. `types: { custom: [step, wisp] }`)
// or the legacy comma-separated string form (e.g.
// `types.custom = "step,wisp"`). Entries are trimmed; empty entries are

View on GitHub (pinned to 71377f2769)

Solutions

Provide a non-empty filename, e.g. "AGENTS.md", when calling SafeAgentsFile.
Check the config key that supplies the filename and set it in config.yaml if missing.
Guard the call site: skip the write (or use the default name) when the value is an empty string.

Example fix

// before
name := cfg.GetString("agents.file") // ""
err := config.SafeAgentsFile(name)
// after
name := cfg.GetString("agents.file")
if name == "" {
    name = "AGENTS.md" // default
}
err := config.SafeAgentsFile(name)

Defensive patterns

Strategy: validation

Validate before calling

func validAgentsName(name string) bool {
    return name != ""
}
if !validAgentsName(cfg.AgentsFile) {
    cfg.AgentsFile = "AGENTS.md" // default
}

Try / catch

if err := config.SafeAgentsFile(name); err != nil {
    if strings.Contains(err.Error(), "must not be empty") {
        return fmt.Errorf("agents file not configured; set it in config.yaml or pass -agents-file")
    }
    return err
}

Prevention

Provide a sensible default (e.g. AGENTS.md) whenever the config value is empty.
Validate CLI flags with required-field checks before reaching the config layer.
After renaming config keys, grep for old lookups that now return empty strings.
Log the source of empty values (env vs config) to speed diagnosis.

When it happens

Trigger: Calling ValidateAgentsFile("") directly, or SafeAgentsFile with an empty filename — commonly from an unset config value or an unfilled CLI flag.

Common situations: The agents-file setting is missing from config.yaml; a script passes an empty variable; a config key was renamed and the old lookup now returns "".

Related errors

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