{"record":{"id":"b354e762cc882ebf","repo":"gastownhall/beads","slug":"agents-file-name-exceeds-255-characters","errorCode":null,"errorMessage":"agents file name exceeds 255 characters","messagePattern":"agents file name exceeds 255 characters","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/config/config.go","lineNumber":1173,"sourceCode":"func SafeAgentsFile() string {\n\tname := AgentsFile()\n\tif err := ValidateAgentsFile(name); err != nil {\n\t\tdebug.Logf(\"config: agents.file %q failed validation (%v), using default\", name, err)\n\t\treturn DefaultAgentsFile\n\t}\n\treturn name\n}\n\n// ValidateAgentsFile checks that filename is safe to use as an agents file path.\n// It rejects absolute paths, path separators, names longer than 255 characters,\n// and non-markdown extensions. This is a pure string validation function — I/O\n// checks (e.g. symlink detection) are deferred to the file write layer.\nfunc ValidateAgentsFile(filename string) error {\n\tif filename == \"\" {\n\t\treturn fmt.Errorf(\"agents file name must not be empty\")\n\t}\n\tif len(filename) > 255 {\n\t\treturn fmt.Errorf(\"agents file name exceeds 255 characters\")\n\t}\n\tif strings.ContainsAny(filename, \"/\\\\\") {\n\t\treturn fmt.Errorf(\"agents file must be a simple filename without path separators, got %q\", filename)\n\t}\n\text := strings.ToLower(filepath.Ext(filename))\n\tif ext != \".md\" {\n\t\treturn fmt.Errorf(\"agents file must have .md extension, got %q\", ext)\n\t}\n\treturn nil\n}\n\n// getConfigList retrieves a list-typed configuration value from config.yaml,\n// accepting either the YAML list form (e.g. `types: { custom: [step, wisp] }`)\n// or the legacy comma-separated string form (e.g.\n// `types.custom = \"step,wisp\"`). Entries are trimmed; empty entries are\n// dropped. The dual-form support is required for project-extension\n// types/statuses declared in .beads/config.yaml — see gastownhall/beads#4024.\nfunc getConfigList(key string) []string {","sourceCodeStart":1155,"sourceCodeEnd":1191,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/config/config.go#L1155-L1191","documentation":"ValidateAgentsFile caps the agents file name at 255 characters, matching typical filesystem filename limits, to prevent ENAMETOOLONG errors at write time. Names longer than 255 bytes are rejected up front with this error.","triggerScenarios":"Calling ValidateAgentsFile or SafeAgentsFile with a filename whose length exceeds 255 characters — often from concatenating prefixes, timestamps, or an entire path into the name argument.","commonSituations":"Generated names built by templates that interpolate long IDs; a user pastes a full path into a setting that expects a bare filename; locale/multibyte names push length over the limit.","solutions":["Shorten the filename to 255 characters or fewer.","Strip any directory components and pass only the base name (paths are rejected separately).","If the name is generated, truncate or hash the variable portion to fit the limit."],"exampleFix":"// before\nname := \"agents-\" + longTaskID + \"-notes.md\" // >255 chars\n// after\nname := \"agents-\" + longTaskID[:8] + \"-notes.md\"","handlingStrategy":"validation","validationCode":"const maxNameLen = 255\nif len(name) > maxNameLen {\n    return fmt.Errorf(\"agents file name %d > %d chars\", len(name), maxNameLen)\n}","typeGuard":null,"tryCatchPattern":"if err := config.SafeAgentsFile(name); err != nil {\n    if strings.Contains(err.Error(), \"exceeds 255\") {\n        return fmt.Errorf(\"shorten the agents file name (got %d chars)\", len(name))\n    }\n    return err\n}","preventionTips":["Truncate generated names with a hash suffix instead of long raw IDs.","Keep templates that build filenames bounded in length.","Pass bare filenames, never paths, into the agents-file API.","Add a unit test asserting generated names stay within 255 chars."],"tags":["config","validation","filename","length-limit"],"backgroundTag":"filename-too-long","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}