Detecting and Fixing Replica Lag in Algolia Indices: A Step‑by‑Step Diagnostic Guide

Problem Statement

Queries return outdated or missing records and response latency exceeds 5 seconds after recent writes. This indicates replica lag, a delay between primary writes and replica synchronization.

Diagnostic Overview

Replica lag is the time a replica takes to apply changes from the primary. Algolia expects lag ≤ 1 second; observed lag > 5 seconds signals a problem.

Diagnostic Table

Metric	Expected	Observed
Replica lag	≤ 1 s	> 5 s
Error codes	None	503, 429

Ordered Checks

1. Verify primary index status: Open the Algolia dashboard, select the index, and confirm the primary status is “active”. Permissions: admin API key required.
2. Query replica health endpoint: Run GET https://{APPLICATION_ID}-dsn.algolia.net/1/indices/{INDEX_NAME}/replicas. Check the lag field and status. Permissions: read‑only API key.
3. Inspect replication logs: Use the log viewer or CLI algolia logs tail --index {INDEX_NAME} to look for timeout or network errors. Permissions: read access to logs.
4. Measure network RTT: Execute ping -c 5 {REPLICA_HOST} from the primary node. High RTT (> 100 ms) may cause lag. Permissions: network admin.

Fixes Tied to Findings

• Restart indexing job: If logs show a stalled job, restart it via the dashboard or POST /1/indexing/jobs/{JOB_ID}/restart. Risk: temporary load spike.
• Increase replica count: Add replicas in the dashboard or via PUT /1/indices/{INDEX_NAME} with a higher replicaCount. Verify cluster capacity first; may cause brief downtime.
• Enable sync mode: Set syncMode=manual to force immediate replication. Trade‑off: higher load on primary.
• Clear index cache: Issue POST /1/indices/{INDEX_NAME}/clearCache. This forces replicas to fetch fresh data; may increase latency momentarily.
• Full reindex: Run POST /1/indexing/jobs with type=full. Schedule during low traffic to avoid query slowdown.

Escalation Criteria

If replica lag remains > 30 seconds after a full reindex, open a support ticket. Include:

• Replica health snapshots from the health endpoint.
• Replication log excerpts showing errors.
• Network RTT measurements.
• Current replica count and cluster configuration.

Verification After Fix

1. Re‑run the diagnostic query; confirm replica lag ≤ 1 s via the health endpoint.
2. Check application logs for error‑free responses and verify query latency < 500 ms.
3. Monitor replica health metrics for at least 15 minutes; lag should stay within the expected range.

Practical Example

# Example: increase replica count via API
curl -X PUT "https://{APPLICATION_ID}-dsn.algolia.net/1/indices/{INDEX_NAME}" \
  -H "X-Algolia-API-Key: {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"replicaCount": 3}'

After the change, re‑run the health check; lag should drop below 1 second within a few minutes.

Limitations and Risks

• Full reindexing temporarily raises cluster load and can affect query latency; schedule during off‑peak hours.
• Changing replica count may cause brief downtime if capacity is insufficient; verify available nodes before adjusting.
• Disabling sync mode can increase lag; understand the trade‑off between immediacy and resource usage.