benbjohnson/litestream · error

checkpoint failed: %w

Error message

checkpoint failed: %w

What it means

This error wraps failure of the `PRAGMA wal_checkpoint(<mode>)` scan in `runCheckpoint`. It means SQLite refused the checkpoint command — the mode string was invalid, the database is not in WAL mode, or the checkpoint could not be executed (e.g. locked by another connection). `shrinkDatabase` calls it after deletes so the WAL is merged before VACUUM.

Source

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

	slog.Debug("Deleted rows from table",
		"table", table,
		"rows_deleted", rowsDeleted,
		"duration", duration,
	)

	return rowsDeleted, nil
}

func (c *ShrinkCommand) runCheckpoint(db *sql.DB) error {
	slog.Info("Running checkpoint", "mode", c.CheckpointMode)

	startTime := time.Now()
	query := fmt.Sprintf("PRAGMA wal_checkpoint(%s)", c.CheckpointMode)

	var busy, written, total int
	err := db.QueryRow(query).Scan(&busy, &written, &total)
	if err != nil {
		return fmt.Errorf("checkpoint failed: %w", err)
	}

	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()

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Pass a valid mode: PASSIVE, FULL, RESTART, or TRUNCATE
2. Verify the DB is in WAL mode: `PRAGMA journal_mode;` — switch with `PRAGMA journal_mode=WAL;`
3. Close other database connections before checkpointing
4. Inspect the wrapped `%w` error for the specific SQLite error

Example fix

// before
litestream-test shrink --checkpoint-mode TRUNCATEE
// after
litestream-test shrink --checkpoint-mode TRUNCATE

mode := strings.ToUpper(c.CheckpointMode)
switch mode {
case "PASSIVE", "FULL", "RESTART", "TRUNCATE":
default:
	return fmt.Errorf("invalid checkpoint mode %q", mode)
}

When it happens

Trigger: Invalid `--checkpoint-mode` value (valid: PASSIVE, FULL, RESTART, TRUNCATE); database not opened in WAL mode; another connection blocking the checkpoint (returns busy but scan still succeeds — error here is driver-level failure); corrupted database.

Common situations: Typo in the checkpoint mode flag; shrink targeting a journal-mode DELETE database; long-running readers preventing checkpoint completion in conjunction with lock errors.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

• checkpoint: %w
• set synchronous: %w
• count rows: %w
• get table info: %w
• delete rows: %w

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