benbjohnson/litestream · error

remote position: %w

Error message

remote position: %w

What it means

DB.SyncStatus() wraps any error from db.Replica.calcPos(ctx) with "remote position". calcPos determines the replica's remote TXID by querying the replica's storage backend (listing LTX files / latest snapshot). This error means the remote position could not be determined — usually a storage-backend or network failure, not a local database problem.

Source

Thrown at db.go:704

	InSync     bool
}

// SyncStatus returns the current replication status of the database, comparing
// the local transaction position against the remote replica position. The remote
// position is queried from the replica storage, so this method may perform I/O.
func (db *DB) SyncStatus(ctx context.Context) (SyncStatus, error) {
	if db.Replica == nil {
		return SyncStatus{}, fmt.Errorf("no replica configured")
	}

	localPos, err := db.Pos()
	if err != nil {
		return SyncStatus{}, fmt.Errorf("local position: %w", err)
	}

	remotePos, err := db.Replica.calcPos(ctx)
	if err != nil {
		return SyncStatus{}, fmt.Errorf("remote position: %w", err)
	}

	return SyncStatus{
		LocalTXID:  localPos.TXID,
		RemoteTXID: remotePos.TXID,
		InSync:     localPos.TXID > 0 && localPos.TXID == remotePos.TXID,
	}, nil
}

// SyncAndWait performs a full sync: WAL to LTX files, then LTX files to remote
// replica. Blocks until both stages complete.
func (db *DB) SyncAndWait(ctx context.Context) error {
	if db.Replica == nil {
		return fmt.Errorf("no replica configured")
	}

	if err := db.Sync(ctx); err != nil {
		return fmt.Errorf("db sync: %w", err)

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Inspect the wrapped error to identify which storage backend call failed.
2. Verify replica client config (bucket, path/endpoint, region, credentials) with a direct listing of the replica location.
3. Check network connectivity / VPC endpoints to the storage provider and retry.
4. If remote layout is suspect, inspect it with `litestream ltx -level all` and restore/re-replicate as needed.

// preflight: verify replica is reachable before status checks
// e.g. list the replica root with the same client config in a health check

var status SyncStatus
var err error
for i := 0; i < 3; i++ {
    if status, err = db.SyncStatus(ctx); err == nil {
        break
    }
    if !errors.Is(err, context.DeadlineExceeded) && !isTransient(err) {
        break
    }
    time.Sleep(backoff)
}

When it happens

Trigger: Calling db.SyncStatus(ctx) when the replica client fails to list/read remote LTX info: network outage, wrong bucket/container/credentials, or an empty/invalid remote layout that calcPos cannot interpret.

Common situations: S3/GCS/Azure credentials expired or wrong region; replica path misconfigured after a provider migration; remote replica was reset and holds no recognizable LTX layout; transient network errors during a status check.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

• replica sync: %w
• no snapshots available
• abs: cannot delete ltx file %q: %w
• abs: cannot list blobs: %w
• abs: cannot delete blob %q: %w

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