benbjohnson/litestream · error
validation failed
Error message
validation failed
What it means
Sentinel result of `ValidateCommand.reportResults`: at least one post-restore validation check (row counts, checksums, etc.) did not match between the source database and the restored replica. Unlike the other errors it is not wrapped driver output — it is the tool's summary verdict that replication integrity failed. Check the preceding log output for which specific checks failed.
Source
Thrown at cmd/litestream-test/validate.go:459
func (c *ValidateCommand) reportResults(results []ValidationResult) error {
allPassed := true
for _, result := range results {
if !result.Passed {
allPassed = false
slog.Error("Validation failed",
"check_type", result.CheckType,
"error", result.ErrorMessage,
)
}
}
if allPassed {
slog.Info("All validation checks passed")
return nil
}
return fmt.Errorf("validation failed")
}
func (c *ValidateCommand) Usage() {
fmt.Fprintln(c.Main.Stdout, `
Validate replication integrity by restoring and checking databases.
Usage:
litestream-test validate [options]
Options:
-source-db PATH
Original database path (required)
-replica-url URL
Replica URL to validate
View on GitHub (pinned to 4ed7a308f6)
Solutions
- Read the per-check failure lines logged by reportResults to see which checks mismatched
- Quiesce writes to the source (or wait for `litestream replicate` to catch up) and re-run validation
- Delete the stale `.restored` DB and restore fresh from the replica before validating
- Inspect replica storage (`litestream ltx -level all`) for missing/damaged LTX files
Defensive patterns
Strategy: validation
Validate before calling
// before validating, ensure replica is caught up litestream replicate // wait / check status litestream ltx // verify latest txid matches source
Try / catch
if err := validateCmd.Run(ctx, args...); err != nil && err.Error() == "validation failed" {
// parse earlier log lines for which checks mismatched
return fmt.Errorf("replication integrity check failed; see logs: %w", err)
} Prevention
- Quiesce writes or verify replica sync before validating
- Always restore a fresh .restored DB instead of reusing one
- Treat mismatches as real data loss until proven otherwise
When it happens
Trigger: Rows inserted into the source after the last replica sync but before validation; validation compared against a stale restored DB; replica LTX files missing or corrupted so restore is incomplete; comparing checksums of a DB that was legitimately modified between restore and check.
Common situations: Disaster-recovery drills where live writes continue during validation; detecting actual replication data loss; restored from an old generation while the source moved forward.
Understand the failure class
Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.
Related errors
- sync interval must be greater than 0
- replica required before opening database
- replica client required before opening database
- close decoder: %w
- snapshot interval must be greater than 0
AI-assisted analysis of benbjohnson/litestream@4ed7a308f6 (2026-09-06).
Data as JSON: /api/errors/4ca33dbf6206db74.
Report an issue: GitHub.