benbjohnson/litestream · error

pos

Error message

pos: %w

What it means

Wraps DB.Pos() failure at the start of DB.verifyAndSync during a sync. Fires when the database's current replication position (TXID/offset read via the SHM header) cannot be determined, aborting the verification-and-sync step.

Solutions

1. Check permissions on the .litestream meta directory next to the database
2. Run 'litestream reset' to rebuild corrupted local LTX state

When it happens

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

Appendix: source

Thrown at db.go:1344

		s.lastSyncedWALOffset = exec.state.lastSyncedWALOffset
	})

	// Compute current index and total shadow WAL size.
	db.txIDGauge.Set(float64(exec.pos.TXID))

	// Update file size metrics.
	if fi, err := os.Stat(db.path); err == nil {
		db.dbSizeGauge.Set(float64(fi.Size()))
	}
	db.walSizeGauge.Set(float64(exec.state.lastSyncedWALOffset))

	return result, nil
}

func (db *DB) verifyAndSync(ctx context.Context, checkpointing bool, state *syncState) (syncResult, error) {
	pos, err := db.Pos()
	if err != nil {
		return syncResult{}, fmt.Errorf("pos: %w", err)
	}

	return db.verifyAndSyncWithExecutor(ctx, checkpointing, &syncExecutor{
		state: *state,
		pos:   pos,
	}, 0)
}

func (db *DB) verifyAndSyncWithExecutor(ctx context.Context, checkpointing bool, exec *syncExecutor, maxSyncWALBytes int64) (syncResult, error) {
	db.setSyncDiagPhase(diagPhaseStatWAL, func(s *diagState) {
		s.txID = exec.pos.TXID + 1
		s.lastSyncedWALOffset = exec.state.lastSyncedWALOffset
	})

	// Use the last synced WAL offset as the logical size for checkpoint decisions.
	// This avoids using file size which may include stale frames with old salt
	// values after a checkpoint. See issue #997.
	origWALSize := exec.state.lastSyncedWALOffset

View on GitHub (pinned to 4ed7a308f6)