benbjohnson/litestream · error

post-restore integrity check: %w

Error message

post-restore integrity check: %w

What it means

The optional post-restore integrity check (PRAGMA integrity_check / quick_check) failed on the newly restored database. The restored image is corrupt or inconsistent; Litestream removes the output (and -shm/-wal) so a bad database isn't left behind, unless the context was cancelled.

Source

Thrown at replica.go:777

	}

	// Copy file to final location.
	r.Logger().Debug("renaming database from temporary location")
	if err := os.Rename(tmpOutputPath, opt.OutputPath); err != nil {
		return err
	}
	if err := internal.FsyncDir(filepath.Dir(opt.OutputPath)); err != nil {
		return fmt.Errorf("sync restore output dir: %w", err)
	}

	if opt.IntegrityCheck != IntegrityCheckNone {
		if err := checkIntegrity(ctx, opt.OutputPath, opt.IntegrityCheck); err != nil {
			if ctx.Err() == nil {
				_ = os.Remove(opt.OutputPath)
				_ = os.Remove(opt.OutputPath + "-shm")
				_ = os.Remove(opt.OutputPath + "-wal")
			}
			return fmt.Errorf("post-restore integrity check: %w", err)
		}
		r.Logger().Info("post-restore integrity check passed")
	}

	// Enter follow mode if enabled, continuously applying new LTX files.
	if opt.Follow {
		for _, rd := range rdrs {
			if closer, ok := rd.(io.Closer); ok {
				_ = closer.Close()
			}
		}
		rdrs = nil

		maxTXID := infos[len(infos)-1].MaxTXID
		if err := WriteTXIDFile(opt.OutputPath, maxTXID); err != nil {
			return fmt.Errorf("write initial txid file: %w", err)
		}
		return r.follow(ctx, opt.OutputPath, maxTXID, opt.FollowInterval)

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Retry the restore; if it persists the replica's LTX history is corrupt
2. Inspect and repair replica files (litestream ltx, delete bad files)
3. Restore to an earlier timestamp that predates the corruption

When it happens

Trigger: Thrown at replica.go:777 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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