AdguardTeam/AdGuardHome · error

preparing pending file: %w

Error message

preparing pending file: %w

What it means

After creating the temp file, newPendingFile applies the requested mode with os.Chmod; failure produces this error. The code itself notes os.Chmod is 'useless on Windows', so on Windows this mostly surfaces for lock/attribute issues rather than permission bits.

Source

Thrown at internal/aghrenameio/renameio_windows.go:69

	return f.file.Write(b)
}

// NewPendingFile is a wrapper around [os.CreateTemp].
//
// f.Close must be called to finish the renaming.
func newPendingFile(filePath string, mode fs.FileMode) (f PendingFile, err error) {
	// Use the same directory as the file itself, because moves across
	// filesystems can be especially problematic.
	file, err := os.CreateTemp(filepath.Dir(filePath), "")
	if err != nil {
		return nil, fmt.Errorf("opening pending file: %w", err)
	}

	// TODO(e.burkov):  The [os.Chmod] implementation is useless on Windows,
	// investigate if it can be removed.
	err = os.Chmod(file.Name(), mode)
	if err != nil {
		return nil, fmt.Errorf("preparing pending file: %w", err)
	}

	return &pendingFile{
		file:       file,
		targetPath: filePath,
	}, nil
}

View on GitHub (pinned to b41aefbe51)

Solutions

1. Retry once after a short delay to rule out transient AV locks
2. Exclude the working directory from real-time AV scanning
3. If on a network share, write locally and copy instead
4. Contribute upstream: the TODO suggests removing the no-op Chmod on Windows, which eliminates this failure mode

if err != nil && strings.Contains(err.Error(), "preparing pending file") {
    time.Sleep(100 * time.Millisecond)
    // recreate pending file and retry once
}

When it happens

Trigger: os.Chmod failing on the just-created temp file — file locked by AV/indexer at that instant, read-only directory inheritance, or the file already closed/removed by external interference.

Common situations: Antivirus racing newly created files in the data directory; directories enforcing read-only inheritance; exotic filesystems (network shares) not supporting attribute changes.

Related errors

• closing: %w
• renaming: %w
• opening pending file: %w

AI-assisted analysis of AdguardTeam/AdGuardHome@b41aefbe51 (2026-08-27). Data as JSON: /api/errors/ec5ebecc2f63794b. Report an issue: GitHub.