wavetermdev/waveterm · error

failed to write backup metadata: %w

Error message

failed to write backup metadata: %w

What it means

MakeFileBackup writes the .json metadata sidecar next to the .bak file (mode 0600). This error wraps os.WriteFile failing for the metadata file. The .bak file may already exist on disk but the backup is reported as failed because restore depends on the metadata sidecar.

Source

Thrown at pkg/filebackup/filebackup.go:84

	}

	metadata := BackupMetadata{
		FullPath:  absFilePath,
		Timestamp: now.Format(time.RFC3339),
		Perm:      fmt.Sprintf("%04o", fileInfo.Mode().Perm()),
	}

	metadataJSON, err := json.MarshalIndent(metadata, "", "  ")
	if err != nil {
		return "", fmt.Errorf("failed to marshal backup metadata: %w", err)
	}

	metadataName := fmt.Sprintf("%s.%s.%s.json", basename, dirHash8, uuidStr)
	metadataPath := filepath.Join(backupDir, metadataName)

	err = os.WriteFile(metadataPath, metadataJSON, 0600)
	if err != nil {
		return "", fmt.Errorf("failed to write backup metadata: %w", err)
	}

	return backupPath, nil
}

func RestoreBackup(backupFilePath string, restoreToFileName string) error {
	backupData, err := os.ReadFile(backupFilePath)
	if err != nil {
		return fmt.Errorf("failed to read backup file: %w", err)
	}

	metadataPath := backupFilePath[:len(backupFilePath)-4] + ".json"
	metadataData, err := os.ReadFile(metadataPath)
	if err != nil {
		return fmt.Errorf("failed to read backup metadata: %w", err)
	}

	var metadata BackupMetadata

View on GitHub (pinned to a4447c1563)

Solutions

1. Free disk space on the cache volume and retry the operation.
2. Check the dated backup directory for stale/partial .bak files without .json sidecars and clean them up.
3. Check permissions on the backup directory and any file-locking software interference.
4. Retry; if recurring, verify filesystem health (fsck / chkdsk).

Example fix

// before
ls ~/.cache/waveterm/waveai-backups/2026-09-01/  # orphan *.bak without *.json
// after
free disk space, delete orphaned *.bak files, and retry the edit

backupPath, err := filebackup.MakeFileBackup(absPath)
if err != nil {
    if strings.Contains(err.Error(), "write backup metadata") {
        // backup .bak may be orphaned without its .json sidecar
        log.Warnf("backup incomplete, orphaned .bak possible: %v", err)
    }
    return err
}

When it happens

Trigger: os.WriteFile(metadataPath, metadataJSON, 0600) fails after the .bak write succeeded: disk filled between the two writes, metadata path locked by another process, permission change on the backup dir, or I/O error.

Common situations: Disk reaching capacity mid-backup (barely enough for .bak, not for .json); on-demand antivirus scanning interfering on Windows; cache volume flaking out mid-operation.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• failed to write backup file: %w
• failed to stat file for backup: %w
• failed to read file for backup: %w
• failed to create backup directory: %w
• failed to get app directory: %w

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