larksuite/cli · error

cannot stat opened file: %w

Error message

cannot stat opened file: %w

What it means

This error means the OS Stat call on an already-opened file handle failed inside inspectOpenedFile. The library opens the path, then re-stats via the handle to verify nothing changed between path validation and open; if the handle cannot be stat'd, the file's post-open identity is unknown and opening is refused rather than proceeding on an unverifiable handle. It wraps the underlying OS error, so the cause (e.g. deleted file, invalid handle) is in %w.

Source

Thrown at internal/vfs/localfileio/openvalidated_windows.go:44

	if err != nil {
		return nil, err
	}
	if err := inspectOpenedFile(f, pre); err != nil {
		f.Close()
		// An unusable target is a bad argument, not an internal fault: callers
		// map ErrPathValidation to a typed validation error, and the fd checks
		// are the same verdict the path checks make, one layer later.
		return nil, &fileio.PathValidationError{Err: err}
	}
	return f, nil
}

// inspectOpenedFile validates the opened handle. pre is nil when there is no
// prior Stat to compare against.
func inspectOpenedFile(f *os.File, pre os.FileInfo) error {
	post, err := f.Stat()
	if err != nil {
		return fmt.Errorf("cannot stat opened file: %w", err)
	}
	if pre != nil && !os.SameFile(pre, post) {
		return fmt.Errorf("file changed between validation and open")
	}
	if !post.Mode().IsRegular() {
		return fmt.Errorf("not a regular file (directories, devices, FIFOs, and sockets are refused)")
	}
	var handleInfo syscall.ByHandleFileInformation
	if err := syscall.GetFileInformationByHandle(syscall.Handle(f.Fd()), &handleInfo); err != nil {
		return fmt.Errorf("cannot inspect opened file links: %w", err)
	}
	if handleInfo.NumberOfLinks > 1 {
		return fmt.Errorf("file has multiple hard links, so the other names it can be reached by " +
			"cannot be checked (hint: copy the file and use the copy instead)")
	}
	return nil
}

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Retry the open; the failure is often a transient race and a fresh openValidated call will either succeed or give a clearer error
2. Check the wrapped cause (%w) to identify the OS failure (e.g. ERROR_FILE_NOT_FOUND means a concurrent delete)
3. Verify the file is on a healthy local NTFS volume, not a flaky network share or removable drive
4. Exclude the path from antivirus real-time scanning/quarantine if AV is deleting files mid-open

Example fix

// before: no retry, single call
f, err := openValidated(path, preStat)
// after: tolerate transient mid-open failures with bounded retry
var f *os.File
for i := 0; i < 3; i++ {
    f, err = openValidated(path, preStat)
    if err == nil { break }
    time.Sleep(50 * time.Millisecond)
}

info, err := os.Stat(path)
if err != nil { return fmt.Errorf("path not statable before open: %w", err) }
_ = info

var f *os.File
var err error
for i := 0; i < 3; i++ {
    f, err = openValidated(path, pre)
    if err == nil || !strings.Contains(err.Error(), "cannot stat opened file") { break }
    time.Sleep(50 * time.Millisecond)
}
if err != nil { return err }

When it happens

Trigger: Calling openValidated on Windows when the file is deleted or the volume becomes unavailable between opening the handle and calling f.Stat(), or when the returned handle is somehow invalid.

Common situations: Antivirus/quarantine removing the file mid-open, files on network shares or removable drives that drop during access, race with another process deleting the file, or filesystem errors on failing disks.

Related errors

• file changed between validation and open
• %s: cannot stat %q: %w
• file changed between validation and open
• not a regular file (directories, devices, FIFOs, and sockets
• cannot inspect opened file links: %w

AI-assisted analysis of larksuite/cli@7fd6ef3c07 (2026-09-04). Data as JSON: /api/errors/6ac8b1b263f83822. Report an issue: GitHub.