kopia/kopia · warning

FADV_SEQUENTIAL hint for streaming file reads failed

Error message

FADV_SEQUENTIAL hint for streaming file reads failed

What it means

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.

Solutions

1. Check the filesystem backing the file supports fadvise (dmesg/mount output); prefer a local POSIX filesystem for cache/data directories
2. Verify the *os.File is open and not double-closed when HintStreaming is invoked
3. Treat this as non-fatal if the caller allows: the hint is advisory and reads still work without it
4. Update the kernel/container environment if an old kernel or restricted seccomp profile blocks fadvise

if _, err := os.Stat(path); err != nil {
    return err // file must exist and be open before hinting
}

if err := iomem.HintStreaming(f); err != nil {
    log.Printf("read-ahead hint failed (non-fatal): %v", err)
    // proceed with normal reads; hint is advisory
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

Related errors

• FADV_DONTNEED hint for releasing file I/O memory failed
• Control
• GetCapacity
• GetCapacity
• SyscallConn

AI-assisted analysis of kopia/kopia@82495e54b5 (2026-09-07). Data as JSON: /api/errors/00e23f935e89f744. Report an issue: GitHub.

Appendix: source

Thrown at internal/iomem/iomem_linux.go:22

// about page cache usage for accessed files.
package iomem

import (
	"os"

	"github.com/pkg/errors"
	"golang.org/x/sys/unix"
)

// HintStreaming advises the kernel that this file will be read sequentially,
// once. Call it immediately after opening a file for backup so the hint
// lands before any reads populate the page cache.
func HintStreaming(f *os.File) error {
	err := callWithFd(f, func(fd int) error {
		return unix.Fadvise(fd, 0, 0, unix.FADV_SEQUENTIAL)
	})

	return errors.Wrap(err, "FADV_SEQUENTIAL hint for streaming file reads failed")
}

// HintNotNeeded advises the kernel that cached pages for this file are no
// longer needed and can be reclaimed. Call it after reading is done.
func HintNotNeeded(f *os.File) error {
	err := callWithFd(f, func(fd int) error {
		return unix.Fadvise(fd, 0, 0, unix.FADV_DONTNEED)
	})

	return errors.Wrap(err, "FADV_DONTNEED hint for releasing file I/O memory failed")
}

// callWithFd runs op against f's underlying file descriptor.
//
// It uses SyscallConn().Control() rather than f.Fd() for two reasons:
//
//   - Async/blocking: on Linux, regular files opened via os.Open are
//     put into non-blocking mode and registered with Go's runtime

View on GitHub (pinned to 82495e54b5)