{"record":{"id":"00e23f935e89f744","repo":"kopia/kopia","slug":"fadv-sequential-hint-for-streaming-file-reads-fail","errorCode":null,"errorMessage":"FADV_SEQUENTIAL hint for streaming file reads failed","messagePattern":"FADV_SEQUENTIAL hint for streaming file reads failed","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"internal/iomem/iomem_linux.go","lineNumber":22,"sourceCode":"// about page cache usage for accessed files.\npackage iomem\n\nimport (\n\t\"os\"\n\n\t\"github.com/pkg/errors\"\n\t\"golang.org/x/sys/unix\"\n)\n\n// HintStreaming advises the kernel that this file will be read sequentially,\n// once. Call it immediately after opening a file for backup so the hint\n// lands before any reads populate the page cache.\nfunc HintStreaming(f *os.File) error {\n\terr := callWithFd(f, func(fd int) error {\n\t\treturn unix.Fadvise(fd, 0, 0, unix.FADV_SEQUENTIAL)\n\t})\n\n\treturn errors.Wrap(err, \"FADV_SEQUENTIAL hint for streaming file reads failed\")\n}\n\n// HintNotNeeded advises the kernel that cached pages for this file are no\n// longer needed and can be reclaimed. Call it after reading is done.\nfunc HintNotNeeded(f *os.File) error {\n\terr := callWithFd(f, func(fd int) error {\n\t\treturn unix.Fadvise(fd, 0, 0, unix.FADV_DONTNEED)\n\t})\n\n\treturn errors.Wrap(err, \"FADV_DONTNEED hint for releasing file I/O memory failed\")\n}\n\n// callWithFd runs op against f's underlying file descriptor.\n//\n// It uses SyscallConn().Control() rather than f.Fd() for two reasons:\n//\n//   - Async/blocking: on Linux, regular files opened via os.Open are\n//     put into non-blocking mode and registered with Go's runtime","sourceCodeStart":4,"sourceCodeEnd":40,"githubUrl":"https://github.com/kopia/kopia/blob/82495e54b584c1ef6073c9e1be048f57f8aef078/internal/iomem/iomem_linux.go#L4-L40","documentation":"HintStreaming issues posix_fadvise(FADV_SEQUENTIAL) on a file descriptor to tell the kernel the file will be read sequentially from start to end, enabling aggressive read-ahead. The error wraps a failed Fadvise syscall, which is unusual since the hint is advisory — a failure here means the fd or filesystem rejected the operation.","triggerScenarios":"Calling Open() -> HintStreaming(f) where f is invalid or already closed, the filesystem does not support posix_fadvise (e.g. some network mounts like NFS on certain kernels, or overlay filesystems), or the syscall returns EBADF/EINVAL.","commonSituations":"Running Kopia on a filesystem lacking fadvise support (some FUSE mounts, containerized overlayfs edge cases); file closed concurrently by another goroutine; exotic storage backends mounted into the cache directory.","solutions":["Check the filesystem backing the file supports fadvise (dmesg/mount output); prefer a local POSIX filesystem for cache/data directories","Verify the *os.File is open and not double-closed when HintStreaming is invoked","Treat this as non-fatal if the caller allows: the hint is advisory and reads still work without it","Update the kernel/container environment if an old kernel or restricted seccomp profile blocks fadvise"],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"if _, err := os.Stat(path); err != nil {\n    return err // file must exist and be open before hinting\n}","typeGuard":null,"tryCatchPattern":"if err := iomem.HintStreaming(f); err != nil {\n    log.Printf(\"read-ahead hint failed (non-fatal): %v\", err)\n    // proceed with normal reads; hint is advisory\n}","preventionTips":["Keep data/cache directories on local POSIX filesystems (ext4/xfs), not FUSE/NFS mounts","Avoid container seccomp profiles that block fadvise","Never double-close files that hints will be applied to"],"tags":["linux","syscall","fadvise","filesystem"],"backgroundTag":"unsupported-platform","analyzedSha":"82495e54b584c1ef6073c9e1be048f57f8aef078","analyzedAt":"2026-09-07T20:35:21.689Z","contentChangedAt":"2026-09-07T20:35:21.689Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}