{"record":{"id":"43c22f1d6f5397e2","repo":"gastownhall/beads","slug":"stat-s-w","errorCode":null,"errorMessage":"stat %s: %w","messagePattern":"stat (.+?): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/doltserver/logrotate.go","lineNumber":89,"sourceCode":"//\n// Behavior:\n//   - maxBytes <= 0: rotation disabled, returns (false, nil).\n//   - primary missing: returns (false, nil). Nothing to rotate.\n//   - primary size <= maxBytes: returns (false, nil). Leave alone.\n//   - primary size > maxBytes: rename to <primary>.1 and return (true, nil).\n//   - rename fails: returns (false, err).\n//\n// The caller should treat errors as non-fatal and proceed to open the log.\nfunc rotateLogIfOversized(primary string, maxBytes int64) (bool, error) {\n\tif maxBytes <= 0 {\n\t\treturn false, nil\n\t}\n\tinfo, err := os.Stat(primary)\n\tif err != nil {\n\t\tif os.IsNotExist(err) {\n\t\t\treturn false, nil\n\t\t}\n\t\treturn false, fmt.Errorf(\"stat %s: %w\", primary, err)\n\t}\n\tif info.Size() <= maxBytes {\n\t\treturn false, nil\n\t}\n\trotated := rotatedLogPath(primary)\n\t// os.Rename overwrites the destination on both Unix and Windows (Go's\n\t// Rename wraps MoveFileEx with MOVEFILE_REPLACE_EXISTING on Windows).\n\tif err := os.Rename(primary, rotated); err != nil {\n\t\treturn false, fmt.Errorf(\"rotating %s -> %s: %w\", primary, rotated, err)\n\t}\n\treturn true, nil\n}\n\n// maybeRotateLog is the convenience wrapper used by Start(). It rotates the\n// dolt-server log if it is oversized and emits a debug message on both\n// rotation and error paths. It never returns an error — rotation is\n// best-effort and must not block server startup.\nfunc maybeRotateLog(beadsDir string) {","sourceCodeStart":71,"sourceCodeEnd":107,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/doltserver/logrotate.go#L71-L107","documentation":"rotateLogIfOversized wraps os.Stat(primary) failures as \"stat %s: %w\". A missing log file is deliberately treated as a no-op (returns false, nil); this error is thrown only for other stat failures such as permission problems or I/O errors. It prevents bd from deciding whether the dolt-server log needs rotation.","triggerScenarios":"maybeRotateLog calls rotateLogIfOversized and os.Stat on the primary dolt-server log fails with something other than NotExist: permission denied on the log directory, an I/O error, or a broken path component (e.g. parent is a file).","commonSituations":"The .beads/ or log directory was created by another user (root) and bd now runs unprivileged; the log path points across a flaky network mount; filesystem errors on disk-full volumes.","solutions":["Fix permissions on the log file and its directory so the bd user can stat it (chmod/chown).","Verify the log path's parent directories exist and none of them is a regular file.","Check disk health / mount state if the error is an I/O error (dmesg, mount output).","If the path is wrong, correct the server log path configuration and restart."],"exampleFix":"// before\ninfo, err := os.Stat(primary)\nif err != nil {\n    if os.IsNotExist(err) {\n        return false, nil\n    }\n    return false, fmt.Errorf(\"stat %s: %w\", primary, err)\n}\n// after\n// ensure the directory is writable by the bd user first:\n//   sudo chown -R $(whoami) .beads/logs\n// then retry the command that started the server","handlingStrategy":"validation","validationCode":"if _, err := os.Stat(filepath.Dir(primary)); err != nil {\n    return fmt.Errorf(\"log dir unavailable: %w\", err)\n}\nif f, err := os.OpenFile(primary, os.O_APPEND|os.O_CREATE, 0o644); err == nil {\n    f.Close()\n}","typeGuard":"func logStatOk(path string) bool {\n    _, err := os.Stat(path)\n    return err == nil || os.IsNotExist(err) // both are safe for rotation\n}","tryCatchPattern":"rotated, err := rotateLogIfOversized(primary, maxBytes)\nif err != nil {\n    if errors.Is(err, fs.ErrPermission) {\n        log.Printf(\"cannot rotate log %s: fix permissions\", primary)\n    }\n    return err\n}","preventionTips":["Ensure the log directory is owned/writable by the bd user","Avoid running bd as root and then as a normal user on the same workspace","Check parent path components are directories, not files","Monitor disk/mount health if logs live on network storage"],"tags":["filesystem","logging","permissions","log-rotation"],"backgroundTag":"file-stat-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}