benbjohnson/litestream · error

vacuum failed: %w

Error message

vacuum failed: %w

What it means

This error wraps failure of the `VACUUM` statement in `runVacuum`, the final step of the shrink command that rebuilds the database file to reclaim space. VACUUM fails when the disk lacks free space for the temporary copy, other transactions are open, or the database is not writable. It is thrown by `ShrinkCommand.runVacuum` and aborts the shrink.

Source

Thrown at cmd/litestream-test/shrink.go:278

	duration := time.Since(startTime)
	slog.Info("Checkpoint complete",
		"mode", c.CheckpointMode,
		"busy", busy,
		"pages_written", written,
		"total_pages", total,
		"duration", duration,
	)

	return nil
}

func (c *ShrinkCommand) runVacuum(db *sql.DB) error {
	slog.Info("Running VACUUM (this may take a while)")

	startTime := time.Now()
	_, err := db.Exec("VACUUM")
	if err != nil {
		return fmt.Errorf("vacuum failed: %w", err)
	}

	duration := time.Since(startTime)
	slog.Info("VACUUM complete", "duration", duration)

	return nil
}

func (c *ShrinkCommand) Usage() {
	fmt.Fprintln(c.Main.Stdout, `
Shrink a database by deleting data and optionally running VACUUM.

Usage:

	litestream-test shrink [options]

Options:

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Free disk space (VACUUM needs ~2x database size as temp space)
2. Close all other connections/transactions to the database during vacuum
3. Ensure the DB file and temp directory are writable
4. Check the wrapped error message for 'database is locked' or 'disk I/O error' and fix that root cause

Example fix

// before
litestream-test shrink --source-db /mnt/ro/large.db
// after
# mount writable & ensure ~2x DB size free
litestream-test shrink --source-db /mnt/rw/large.db

var fs syscall.Statfs_t
syscall.Statfs(filepath.Dir(dbPath), &fs)
if fs.Bavail*uint64(fs.Bsize) < 2*dbSizeBytes {
	return errors.New("insufficient disk space for VACUUM")
}

When it happens

Trigger: Insufficient disk space for VACUUM's temp copy (needs roughly 2x the DB size); another connection holds an open transaction; database opened read-only; database corrupted.

Common situations: Shrinking multi-GB test databases on small tmpfs/disk; concurrent litestream replication writing during vacuum; running shrink against a read-only mounted volume.

Related errors

• vacuum: %w
• count rows: %w
• get table info: %w
• delete rows: %w
• checkpoint failed: %w

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