What causes "error renaming temp file '%s'" in hyperledger/fabric?

Verify the target directory still exists and is writable at the time of the rename

error renaming temp file '%s'

Error message

error renaming temp file '%s'

What it means

WriteFile achieves atomic persistence by os.Rename of the temp file (.ccpackage.*) to its final name inside the same directory. If the rename fails, the install does not complete and the error is wrapped with the temp file's name.

Source

Thrown at core/chaincode/persistence/persistence.go:69

	}
	defer os.Remove(tmpFile.Name())

	if n, err := tmpFile.Write(data); err != nil || n != len(data) {
		if err == nil {
			err = errors.Errorf(
				"failed to write the entire content of the file, expected %d, wrote %d",
				len(data), n,
			)
		}
		return errors.Wrapf(err, "error writing to temp file '%s'", tmpFile.Name())
	}

	if err := tmpFile.Close(); err != nil {
		return errors.Wrapf(err, "error closing temp file '%s'", tmpFile.Name())
	}

	if err := os.Rename(tmpFile.Name(), filepath.Join(path, name)); err != nil {
		return errors.Wrapf(err, "error renaming temp file '%s'", tmpFile.Name())
	}

	return nil
}

// Remove removes a file from the filesystem - used for rolling back an in-flight
// Save operation upon a failure
func (f *FilesystemIO) Remove(name string) error {
	return os.Remove(name)
}

// ReadFile reads a file from the filesystem
func (f *FilesystemIO) ReadFile(filename string) ([]byte, error) {
	return os.ReadFile(filename)
}

// ReadDir reads a directory from the filesystem
func (f *FilesystemIO) ReadDir(dirname string) ([]os.FileInfo, error) {

View on GitHub (pinned to 2736b63f8f)

Solutions

Verify the target directory still exists and is writable at the time of the rename
Ensure no external process/jobs remove or lock files inside the chaincode install directory
Check the wrapped OS error for the precise cause (ENOENT, EXDEV, EACCES, EISDIR) and fix accordingly
Retry the install once the directory is in a consistent state

Defensive patterns

Strategy: try-catch

Validate before calling

func ensureRenamable(dir, final string) error {
    if info, err := os.Stat(filepath.Join(dir, final)); err == nil && info.IsDir() {
        return errors.New("destination name exists as a directory")
    }
    if err := unix.Access(dir, unix.W_OK); err != nil { return errors.New("dir not writable") }
    return nil
}

Try / catch

if err := io.WriteFile(path, name, data); err != nil {
    if strings.Contains(err.Error(), "error renaming temp file") {
        log.Errorf("install dir state changed during write: %v", err)
        // re-verify directory exists, then retry once
    }
    return err
}

Prevention

Exclude the chaincode install directory from external cleanup jobs (tmpwatch, cron sweeps)
Do not nest files/directories under names the store may use
Keep the data directory on a single filesystem so rename stays same-device

When it happens

Trigger: os.Rename(tmpFile.Name(), filepath.Join(path, name)) fails: target name invalid, cross-device rename (path/name resolution changed), target directory removed mid-operation, or permission problems on the directory.

Common situations: External cleanup job deleting the chaincodes directory while an install is in flight; the destination filename (derived from PackageID) colliding with a directory; exotic mounts where rename semantics differ.

Related errors

AI-assisted analysis of hyperledger/fabric@2736b63f8f (2026-09-04). Data as JSON: /api/errors/83f46e4cbc7e06f4. Report an issue: GitHub.