AdguardTeam/AdGuardHome · error

opening pending file: %w

Error message

opening pending file: %w

What it means

newPendingFile (Windows implementation) creates the temp sibling file with os.CreateTemp in the target's directory; this error means temp-file creation failed — almost always a filesystem permission or path problem in the directory holding the target.

Source

Thrown at internal/aghrenameio/renameio_windows.go:62

	}

	return nil
}

// Write implements the [PendingFile] interface for *pendingFile.
func (f *pendingFile) Write(b []byte) (n int, err error) {
	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. Ensure the target directory exists and is writable by the service account
2. Run the service with an account that has write access to the data dir, or move the data dir to a writable location
3. Free disk space if the volume is full
4. Validate the configured path at startup before attempting writes

dir := filepath.Dir(target)
if fi, err := os.Stat(dir); err != nil || !fi.IsDir() { /* create dir or fail fast */ }
if err := unix.Access(dir, unix.W_OK); err != nil { /* fix permissions */ }

When it happens

Trigger: Calling newPendingFile when filepath.Dir(filePath) doesn't exist, is read-only for the process, is not a directory, or the filesystem is full (ENOSPC); also invalid path characters on Windows.

Common situations: Writing config/data into a directory the service account can't write (Program Files without elevation); stale configured path pointing to a removed directory; full disks.

Related errors

• closing: %w
• renaming: %w
• preparing pending file: %w
• committing transaction: %w

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