benbjohnson/litestream · error

pos: %w

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.

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)

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.