wavetermdev/waveterm · error

failed to rename file: %w

Error message

failed to rename file: %w

What it means

RenameAppFile performs the actual os.Rename(fromPath, toPath) after validating both paths and creating the destination directory. If the kernel-level rename fails, the error is wrapped as "failed to rename file". Common causes are the source file being missing/locked or the two paths residing on different filesystems.

Source

Thrown at pkg/waveappstore/waveappstore.go:403

		return err
	}

	fromPath, err := validateAndResolveFilePath(appDir, fromFileName)
	if err != nil {
		return fmt.Errorf("invalid source path: %w", err)
	}

	toPath, err := validateAndResolveFilePath(appDir, toFileName)
	if err != nil {
		return fmt.Errorf("invalid destination path: %w", err)
	}

	if err := os.MkdirAll(filepath.Dir(toPath), 0755); err != nil {
		return fmt.Errorf("failed to create destination directory: %w", err)
	}

	if err := os.Rename(fromPath, toPath); err != nil {
		return fmt.Errorf("failed to rename file: %w", err)
	}

	return nil
}

func FormatGoFile(appId string, fileName string) error {
	if err := ValidateAppId(appId); err != nil {
		return fmt.Errorf("invalid appId: %w", err)
	}

	appDir, err := GetAppDir(appId)
	if err != nil {
		return err
	}

	filePath, err := validateAndResolveFilePath(appDir, fileName)
	if err != nil {
		return err

View on GitHub (pinned to a4447c1563)

Solutions

1. Confirm the source file exists with os.Stat(fromPath) before renaming
2. Retry the rename — transient locks (Windows AV, editor) often clear quickly; implement retry with backoff
3. Fall back to copy+delete if the error is cross-device (EXDEV)
4. Check permissions/locks on both files; close any process holding the source open

Example fix

// before
err := RenameAppFile(appId, from, to)
// after
if _, err := os.Stat(fromPath); err == nil {
    err = RenameAppFile(appId, from, to)
}

if _, err := os.Stat(fromPath); os.IsNotExist(err) {
	return fmt.Errorf("source file %s does not exist", fromPath)
}

var lastErr error
for i := 0; i < 3; i++ {
	err := RenameAppFile(appId, from, to)
	if err == nil {
		break
	}
	if !strings.Contains(err.Error(), "failed to rename file") {
		return err
	}
	lastErr = err
	time.Sleep(time.Duration(1<<i) * 100 * time.Millisecond)
}
return lastErr

When it happens

Trigger: os.Rename fails because fromPath no longer exists (deleted by another process), the file is open/locked on Windows, or source and destination are on different mounts/devices (EXDEV).

Common situations: Renaming a file concurrently with a delete or app removal; syncing waveapps across a mountpoint; on Windows, an editor or virus scanner holding the file open.

Related errors

• failed to rename temp file %q to %q: %w (also failed to remo
• failed to get app directory: %w
• failed to get builder executable path: %w
• build output not found: %w
• failed to read app manifest: %w

AI-assisted analysis of wavetermdev/waveterm@a4447c1563 (2026-09-01). Data as JSON: /api/errors/74d380c886980ad8. Report an issue: GitHub.