larksuite/cli · error

cannot inspect opened file links: %w

Error message

cannot inspect opened file links: %w

What it means

The Windows API GetFileInformationByHandle failed when the library tried to read ByHandleFileInformation (used to count hard links) for the opened file. The library needs the link count to enforce its hard-link safety check, so when the count cannot be read it refuses the open rather than skipping the check. The wrapped cause carries the underlying syscall error.

Source

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

	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. Move or copy the file onto a local NTFS volume and open it there
2. Inspect the wrapped OS error (%w) to identify the failing syscall and volume type
3. Retry; if caused by transient AV/driver interference, a repeat open often succeeds
4. Use the library's non-validated open path only if the hard-link guarantee is not required for your use case

Example fix

// before: opening directly from a network share
f, err := openValidated(`\\server\share\data.json`, pre)
// after: copy to a local NTFS temp file first
local := filepath.Join(os.TempDir(), "data.json")
if err := copyFile(`\\server\share\data.json`, local); err != nil { return err }
f, err := openValidated(local, nil)

// ensure a local NTFS-style volume
abs, _ := filepath.Abs(path)
vol := filepath.VolumeName(abs)
if vol == "" || isRemoteUNC(vol) { return fmt.Errorf("%s is not on a local volume", abs) }

f, err := openValidated(path, pre)
if err != nil && strings.Contains(err.Error(), "cannot inspect opened file links") {
    // fall back to copying to local temp and opening the copy
    local := filepath.Join(os.TempDir(), filepath.Base(path))
    if cerr := copyFile(path, local); cerr != nil { return cerr }
    f, err = openValidated(local, nil)
}
return err

When it happens

Trigger: Calling openValidated on Windows when GetFileInformationByHandle fails on the freshly opened handle — e.g. unsupported filesystem (FAT32/exFAT network share semantics), handle became invalid, or insufficient permissions on exotic volumes.

Common situations: Files on non-NTFS filesystems or network mounts (SMB shares, WSL mounts) with restricted file information, security software interfering with handle queries, or corrupt/unclean filesystem state.

Related errors

• file has multiple hard links, so the other names it can be r
• %s: cannot stat %q: %w
• cannot stat opened file: %w
• file changed between validation and open
• not a regular file (directories, devices, FIFOs, and sockets

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