benbjohnson/litestream · error

reset failed: %w

Error message

reset failed: %w

What it means

`litestream reset` deletes the database's local LTX state via db.ResetLocalState(ctx). If that removal fails (files locked, permission denied, partial deletion errors), the error is wrapped as "reset failed". Because reset is destructive, a failure here may leave the LTX directory partially removed — the next replication sync will still create a fresh snapshot once the issue is resolved.

Source

Thrown at cmd/litestream/reset.go:119

		if len(files) == 0 {
			fmt.Println("No local LTX files would be removed.")
			return nil
		}

		fmt.Println("Files that would be removed:")
		for _, file := range files {
			fmt.Printf("  %s\n", file)
		}
		fmt.Println("No files were removed.")
		return nil
	}

	// Perform the reset
	fmt.Printf("Resetting local Litestream state for: %s\n", dbPath)
	fmt.Printf("Removing: %s\n", db.LTXDir())

	if err := db.ResetLocalState(ctx); err != nil {
		return fmt.Errorf("reset failed: %w", err)
	}

	fmt.Println("Reset complete. Next replication sync will create a fresh snapshot.")
	return nil
}

func localLTXFiles(root string) ([]string, error) {
	if _, err := os.Stat(root); os.IsNotExist(err) {
		return nil, nil
	} else if err != nil {
		return nil, err
	}

	var files []string
	if err := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
		if err != nil {
			return err
		}

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Stop any other litestream processes or readers holding the LTX dir open, then retry
2. Check the wrapped inner error for permission vs I/O specifics and fix ownership: `chown -R` or run as the db's owning user
3. Verify the filesystem is writable (not mounted ro): `mount | grep <path>`
4. Retry the reset; deletion is idempotent, so a partial previous attempt just finishes

Example fix

// before (litestream still running)
litestream reset /var/lib/db/app.db
// after
systemctl stop litestream
litestream reset /var/lib/db/app.db
systemctl start litestream

// Ensure no other litestream holds the state
if err := exec.Command("pgrep", "-f", "litestream run").Run(); err == nil {
    return fmt.Errorf("litestream is running; stop it before reset")
}

err := runReset(ctx, dbPath)
var perr *fs.PathError
if errors.As(err, &perr) && errors.Is(perr.Err, syscall.EACCES) {
    // retry with elevated permissions or fixed ownership
}
if errors.Is(err, context.Canceled) { /* user aborted mid-delete; re-run */ }

When it happens

Trigger: `litestream reset <dbpath>` where ResetLocalState cannot delete the LTX directory: open file handles/locks on LTX files (another litestream or reader process), permission denied on files or parent dir, read-only filesystem, or context cancellation mid-delete.

Common situations: Two litestream processes running against the same db; resetting while backups/litestream replicate is active; running in containers with read-only volume mounts; SELinux/AppArmor denying deletion.

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

• database does not exist: %w
• dry run failed: %w
• config file not found
• invalid -timestamp, must specify in ISO 8601 format (e.g. 20
• disk full

AI-assisted analysis of benbjohnson/litestream@4ed7a308f6 (2026-09-06). Data as JSON: /api/errors/2427e11712676161. Report an issue: GitHub.