benbjohnson/litestream · error

check database behind replica: %w

Error message

check database behind replica: %w

What it means

db.Open's checkDatabaseBehindReplica (issue #781) failed. This pre-replica-start check reads the replica's TXID to detect a local database that is older than the remote backup (e.g. after a restore from an old copy); failure means the remote TXID could not be queried.

Source

Thrown at db.go:1122

	} else if db.pageSize <= 0 {
		return fmt.Errorf("invalid db page size: %d", db.pageSize)
	}

	// Ensure meta directory structure exists.
	if err := internal.MkdirAll(db.metaPath, db.dirInfo); err != nil {
		return err
	}

	// Ensure WAL has at least one frame in it.
	if err := db.ensureWALExists(ctx); err != nil {
		return fmt.Errorf("ensure wal exists: %w", err)
	}

	// Check if database is behind replica (issue #781).
	// This must happen before replica.Start() to detect restore scenarios.
	if db.Replica != nil {
		if err := db.checkDatabaseBehindReplica(ctx); err != nil {
			return fmt.Errorf("check database behind replica: %w", err)
		}
	}

	// If we have an existing replication files, ensure the headers match.
	// if err := db.verifyHeadersMatch(); err != nil {
	// 	return fmt.Errorf("cannot determine last wal position: %w", err)
	// }

	// TODO(gen): Generate diff of current LTX snapshot and save as next LTX file.

	// Start replication.
	if db.Replica != nil {
		db.Replica.Start(db.ctx)
	}

	return nil
}

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Check replica connectivity and credentials
2. Inspect the wrapped replica client error
3. If the local DB is genuinely behind, restore from the replica or delete the stale database file

When it happens

Trigger: Thrown at db.go:1122 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/16fb9e07f4f8beb4. Report an issue: GitHub.