JusDB
Free DB Audit
NoSQL Databases

Stopping Valkey Full-Resync Loops: Backlog Sizing and Dual-Channel Replication

Find out why Valkey replicas loop on full resyncs, size repl-backlog-size and the replica output buffer from your write rate, and decide when dual-channel replication helps.

JusDB Team
Published November 6, 2026
Updated November 10, 2026
20 min read

A Valkey replica that keeps doing full syncs is easy to spot once you know where to look. The primary's sync_full counter climbs every few minutes, the replica's master_link_status flips between up and down, and the primary log repeats either "Unable to partial resync with replica ... for lack of backlog" or "scheduled to be closed ASAP for overcoming of output buffer limits". Each attempt forks the primary, ships the whole dataset, and blocks the replica while it loads, and a failed attempt starts again from zero. This guide explains why replicas fall back to full syncs, how to size repl-backlog-size and the replica output buffer from your own write rate, and when dual-channel replication helps.

TL;DR
  • A partial resync needs the replica's replication ID to be known to the primary and its offset to still sit inside the primary's backlog. Anything else is a full sync.
  • repl-backlog-size defaults to 10 MB since Valkey 8.0. Size it from the bytes per second that master_repl_offset grows, times the longest disconnect you want to survive, on every node.
  • The default client-output-buffer-limit replica 256mb 64mb 60 cuts off any full sync whose buffered writes stay above 64 MB for 60 seconds. Size it from your write rate times your full sync duration.
  • Dual-channel replication (off by default, set it on both sides) moves the buffered writes to the replica. On 9.x, run 9.0.5 or 9.1.1 or later before you turn it on: earlier releases fail full syncs of hashes with field TTLs.
  • The 9.2 release candidates add replication throttling, stream compression, and forkless full sync. They are not GA yet.

Scope and review date: November 2026. This post covers self-managed Valkey 8.0, 8.1, 9.0, and 9.1 (latest patches 9.1.3 and 9.0.7), with notes on 9.2.0-rc2. Defaults, log messages, and INFO fields were checked against the Valkey documentation, release notes, and the 9.1.3 source on 10 November 2026. The commands were not run in a lab, so rehearse them on staging. On a managed service, check which of these parameters the provider lets you change.


How does a Valkey replica choose between a partial and a full resync?

Every primary has a replication ID and an offset that grows by one for every byte of replication stream it produces. When a replica reconnects, it sends PSYNC with the ID and offset it last processed. The Valkey replication documentation states the rule: if the primary no longer has enough backlog, or the replica refers to a history (replication ID) the primary does not know, a full resynchronization happens.

If both checks pass, the primary replies +CONTINUE and sends the missing bytes. Otherwise it replies +FULLRESYNC, forks a child to produce an RDB snapshot, and buffers every new write until the replica has loaded it.

The PSYNC decision on a Valkey primary

One check decides whether a reconnect costs a few bytes or the whole dataset

Partial resync and full resync paths in Valkey replication Step 1: the replica reconnects and sends PSYNC with the replication ID and the offset it last processed. Step 2: if the primary knows that replication ID and the offset is still inside its replication backlog, it replies +CONTINUE and sends only the missing bytes. Step 3: otherwise it replies +FULLRESYNC and sends a full RDB snapshot, followed by the writes it buffered during the transfer. If the full sync fails, the replica reconnects and starts again at step 1. Replica sends ID + offset Primary checks the backlog Partial resync missing bytes only Full resync RDB, then writes 1 2 ID known and offset in backlog 3 ID unknown, or offset outside backlog failed full sync: the replica asks again

Why it loops: if a full sync is cut off after the replica loaded the snapshot, its next PSYNC asks for the snapshot's offset. With a 10 MB backlog and hundreds of megabytes written since, that offset is gone, so the retry is another full sync.

bash
# On the replica: the ID and offset it will send in PSYNC
valkey-cli -h 10.0.1.11 INFO replication | grep -E "^(master_link_status|master_replid|slave_repl_offset):"

# On the primary: the range its backlog can still serve
valkey-cli -h 10.0.1.10 INFO replication | grep -E "^(master_repl_offset|repl_backlog_first_byte_offset|repl_backlog_histlen):"

Interpretation: a reconnect can resume only if the replica's slave_repl_offset plus one lies between repl_backlog_first_byte_offset and that value plus repl_backlog_histlen. Once the backlog is full, its first byte moves forward with every write.

How do you tell that a replica is stuck in a full-resync loop?

Three INFO counters on the primary tell the story. sync_full counts full resyncs, sync_partial_ok counts accepted partial resyncs, and sync_partial_err counts refused ones (INFO command reference). client_output_buffer_limit_disconnections counts clients cut off for exceeding an output buffer limit; it includes Pub/Sub clients, so read it next to the log.

bash
valkey-cli -h 10.0.1.10 INFO stats | grep -E "^(sync_full|sync_partial_ok|sync_partial_err|client_output_buffer_limit_disconnections):"

Interpretation: one full sync per replica after a restart is normal. sync_full and sync_partial_err rising together, with no matching restarts, is the loop. If client_output_buffer_limit_disconnections rises in step, the output buffer limit is the trigger.

A replica in a full-resync loop

Illustrative output: the message text matches the Valkey 9.1.3 source, but the addresses, IDs, offsets, and counts are invented

valkey@replica-01:~
$ grep -oE "(Trying a partial|Full resync|primary lost).*" valkey.logConnection with primary lost.Trying a partial resynchronization (request 3b7d...91c0:50214432).Full resync from primary: 3b7d...91c0:612340118Connection with primary lost.Trying a partial resynchronization (request 3b7d...91c0:612340119).Full resync from primary: 3b7d...91c0:1248871562$ valkey-cli -h 10.0.1.10 INFO | grep -E "^(sync_|client_out|repl_b)"sync_full:9sync_partial_ok:0sync_partial_err:8client_output_buffer_limit_disconnections:8repl_backlog_active:1repl_backlog_size:10485760repl_backlog_first_byte_offset:1238385803repl_backlog_histlen:10485760

Read it this way: each PSYNC asks for an offset far below the backlog's first byte, and every refused partial resync matches an output buffer disconnect. Both limits need to move. Field meanings are in the INFO reference.

Why does a Valkey replica keep falling back to a full sync?

The primary log names the reason. These are the messages in the 9.1.3 replication source and what each one means.

CauseLog messageWhere to fix it
Backlog too small for the disconnectPrimary: "Unable to partial resync with replica ... for lack of backlog"repl-backlog-size on every node
Writes during a full sync exceed the replica buffer limitPrimary: "Client id=... scheduled to be closed ASAP for overcoming of output buffer limits."client-output-buffer-limit replica on the primary, or dual-channel replication
Snapshot transfer stallsReplica: "Timeout receiving bulk data from PRIMARY..."; primary: "Disconnecting timedout replica (full sync)"Network, disk, repl-timeout
Replica restarted without its replication stateReplica: "Partial resynchronization not possible (no cached primary)"Shut replicas down with SHUTDOWN so the RDB keeps the ID and offset
Different history after a failover or a restarted empty primaryPrimary: "Partial resynchronization not accepted: Replication ID mismatch"Topology, not tuning
bash
grep -E "lack of backlog|Replication ID mismatch|output buffer limits|timedout replica" \
  /var/log/valkey/valkey.log | tail -20

Interpretation: run this on the primary. "lack of backlog" alone means the backlog is the fix. "output buffer limits" a few minutes after "Starting BGSAVE for SYNC" means the full sync itself cannot finish. The replication page adds that a replica restarted from an AOF file cannot partially sync.

How large should repl-backlog-size be?

Valkey 8.0 raised the default from 1 MB to 10 MB (8.0.0-rc2 release notes, #911), and 9.1.3 still ships repl-backlog-size 10mb. The backlog is a ring of recent replication stream bytes, so the question is how many bytes your primary writes during the longest disconnect you want a replica to survive: a network blip, a replica restart, or a failover while other replicas re-point.

Measure the write rate from master_repl_offset, which grows by exactly the number of replication stream bytes. Take the sample during your busiest hour, not an average.

bash
a=$(valkey-cli INFO replication | awk -F: '/^master_repl_offset/ {print $2}' | tr -d '\r')
sleep 60
b=$(valkey-cli INFO replication | awk -F: '/^master_repl_offset/ {print $2}' | tr -d '\r')
echo "replication stream: $(( (b - a) / 60 )) bytes per second"

Interpretation: multiply the result by the disconnect you want to absorb, then add headroom. For example, 5 MB per second and a 60 second outage need 300 MB, so 512 MB leaves margin. This is arithmetic on your own sample, not a benchmark.

bash
# Every node, not just the primary: a promoted replica serves PSYNC from its own backlog
for h in 10.0.1.10 10.0.1.11 10.0.1.12; do
  valkey-cli -h "$h" CONFIG SET repl-backlog-size 512mb
  valkey-cli -h "$h" CONFIG REWRITE
done

Interpretation: repl-backlog-size can be changed at runtime with CONFIG SET. CONFIG REWRITE persists it and fails if the server was started without a config file, in which case edit your deployment template instead. Replicas never free their backlog on the TTL timer, because they may be promoted.

ini
# valkey.conf on the primary and every replica
repl-backlog-size 512mb
# Primary frees the backlog after this many seconds with no replicas (default 3600)
repl-backlog-ttl 3600

Interpretation: the backlog is allocated only once a replica connects, and it fills to its full size under steady writes. Count it in your memory plan beside maxmemory, the replica output buffers, and the fork's copy-on-write memory. mem_total_replication_buffers in INFO memory shows what replication holds right now.

Backlog and buffer share memory

The 9.1.3 valkey.conf notes that a replica's output buffer shares the backlog's memory, and that a replica output buffer limit set below repl-backlog-size is ignored in favor of the backlog size.

How do you keep a full sync inside the output buffer and timeout limits?

A larger backlog does not help a replica that cannot finish its first full sync. During a classic (single-channel) full sync, the primary holds every write since the snapshot point in that replica's output buffer until the replica has received and loaded the RDB. The 9.1.3 default is client-output-buffer-limit replica 256mb 64mb 60: the replica is cut off immediately at 256 MB, or once the buffer stays above 64 MB for 60 seconds in a row.

The soft limit is the usual trap. At 1 MB per second of writes, the buffer passes 64 MB after about 64 seconds and the replica is cut off about 60 seconds later. With defaults, any full sync longer than roughly two minutes at that write rate cannot finish.

Measure how long a full sync takes

bash
# On the replica: time from the FULLRESYNC reply to a finished load
grep -E "Full resync from primary|sync: Finished with success" /var/log/valkey/valkey.log | tail -4

Interpretation: the gap between the timestamps covers transfer and load. If the second line never appears, the gap to the next "Connection with primary lost." is how long the sync survived. Write rate times that duration, plus headroom, is the buffer you need.

bash
valkey-cli -h 10.0.1.10 CONFIG SET client-output-buffer-limit "replica 2gb 1gb 300"
valkey-cli -h 10.0.1.10 CONFIG GET client-output-buffer-limit

Interpretation: CONFIG GET returns all three classes in bytes, and labels the replica class with its legacy name: normal 0 0 0 slave 2147483648 1073741824 300 pubsub 33554432 8388608 60. Setting either limit to 0 disables it. Raise the limits on the primary first; that is where the classic full sync buffers.

Slow transfers and repl-timeout

repl-timeout (default 60 seconds) covers the bulk transfer from the replica's side and the link in both directions. A replica that receives nothing for that long logs "Timeout receiving bulk data from PRIMARY... If the problem persists try to set the 'repl-timeout' parameter in valkey.conf to a larger value." A diskless primary whose writes to a replica stall logs "Disconnecting timedout replica (full sync)". Raise the timeout only after you rule out a saturated link or a slow replica disk.

The transfer defaults matter here too: repl-diskless-sync yes streams the snapshot straight to the socket after a 5 second repl-diskless-sync-delay, and repl-diskless-load disabled makes the replica write it to a temporary file before loading. swapdb loads from the socket but needs memory for both datasets.

What does dual-channel replication change?

Dual-channel replication, added in Valkey 8.0, opens a second connection for the full sync. The RDB snapshot travels on one channel while the replica receives and buffers the live write stream on the other. The primary stops holding those writes, and the replica holds them instead. The Valkey 8.0 announcement reports that in scenarios with heavy read commands, sync time can be cut by up to 50% in the project's own tests.

Single-channel and dual-channel full sync in Valkey

Switch modes to see where writes pile up and which limit ends the sync

Single-channel (default)

AspectSingle-channel
Connections per syncing replicaOne
Writes during the sync are held byThe primary, in that replica's output buffer
Limit that cuts the sync offPrimary's client-output-buffer-limit replica, hard or soft
Primary requirementDiskless or disk-based sync
How to turn it onDefault behavior
Replica entries on the primarytype=replica, state wait_bgsave, send_bulk, online
Memory to watchPrimary: mem_total_replication_buffers
Hashes with field TTLs on 9.xFull syncs work

Dual-channel

AspectDual-channel
Connections per syncing replicaTwo: an RDB channel and a main channel
Writes during the sync are held byThe replica, in a local buffer; the primary only after the replica's limit
Limit that cuts the sync offReplica's own hard limit, then the primary's limit for the overflow
Primary requirementrepl-diskless-sync yes
How to turn it ondual-channel-replication-enabled yes on primary and replica
Replica entries on the primarytype=rdb-channel and type=main-channel, state bg_transfer; rdb_transmitted from 9.1
Memory to watchReplica: replicas_repl_buffer_size; mem_replicas_repl_buffer from 9.1
Hashes with field TTLs on 9.xFails before 9.0.5 and 9.1.1

Trade-off: the primary stops buffering, but the replica needs free memory for the writes that arrive during the sync. Size the replica's own client-output-buffer-limit replica hard limit for that.

The 9.1.3 valkey.conf describes the buffer rule: on the replica, the local buffer is limited by the hard limit of the replica's own client-output-buffer-limit replica. At that point the replica logs "Replication buffer limit reached ... stopping buffering. Further accumulation will occur on primary side." From then on, the primary's limit applies. Dual-channel is off by default (dual-channel-replication-enabled no), and changing it does not affect a sync that is already running.

bash
# Primary first: dual-channel needs diskless sync on the primary
valkey-cli -h 10.0.1.10 CONFIG GET repl-diskless-sync
valkey-cli -h 10.0.1.10 CONFIG SET dual-channel-replication-enabled yes
# Then each replica, with a hard limit sized for writes during a full sync
valkey-cli -h 10.0.1.11 CONFIG SET dual-channel-replication-enabled yes
valkey-cli -h 10.0.1.11 CONFIG SET client-output-buffer-limit "replica 2gb 0 0"

Interpretation: on the replica, this limit also applies to any replicas chained below it. If the primary has repl-diskless-sync no, it logs "Dual channel capability ignored: repl-diskless-sync disabled" and falls back to a single-channel sync. The replica's soft limit is not checked for this local buffer, only the hard limit.

bash
# Primary: a dual-channel sync shows two entries for one replica
valkey-cli -h 10.0.1.10 INFO replication | grep "^slave"
# Replica: the local buffer during the sync
valkey-cli -h 10.0.1.11 INFO replication | grep "^replicas_repl_buffer"
valkey-cli -h 10.0.1.11 INFO memory | grep "^mem_replicas_repl_buffer"

Interpretation: while the sync runs, expect one line with type=rdb-channel and one with state=bg_transfer and type=main-channel; afterwards, a single line with state=online and type=replica. Before 9.1, INFO memory counted the replica's buffer as dataset memory; 9.1 reports it as mem_replicas_repl_buffer (9.1.0-rc1 release notes, #2924).

Which Valkey versions break dual-channel full syncs of hashes with field TTLs?

Valkey 9.0 added per-field expiration for hashes (HEXPIRE, HSETEX, HGETEX and related commands). Those hashes need RDB version 80. In dual-channel replication, the RDB channel's handshake did not send the replica's version, so the primary fell back to RDB version 11, could not encode the hash, and aborted the save (pull request #4105). The bug report, issue #4103, quotes the primary's log line: Can't store key 'myhash' (db 0) in RDB version 11. The replica then retries without end.

The fix shipped in 9.0.5 and 9.1.1 on 21 July 2026 (9.1.1 release notes). That leaves 9.0.0 to 9.0.4 and 9.1.0 affected when dual-channel is on and any hash carries field TTLs. Valkey 8.x has no hash field TTLs and is not affected by this path.

bash
valkey-cli INFO server | grep "^valkey_version"
valkey-cli CONFIG GET dual-channel-replication-enabled
grep "in RDB version 11" /var/log/valkey/valkey.log | tail -3

Interpretation: any match on the primary while dual-channel is on is this bug. Upgrade to the newest patch, which is 9.1.3 or 9.0.7 as of November 2026, or turn dual-channel off on the primary until you can. The guide to Valkey RDB versions 11, 80, and 81 explains what those version numbers mean for upgrades and rollbacks.

Do not enable dual-channel on an affected 9.x build

Turning it on to fix a resync loop on 9.0.0 to 9.0.4 or 9.1.0 can replace a slow loop with one that never finishes, as soon as the application writes a hash with a field TTL.

How do you stop a resync loop step by step?

The runbook below changes only runtime settings, so it needs no restart. It assumes a primary at 10.0.1.10 and a replica at 10.0.1.11; add --user, --pass, or --tls flags as your deployment requires.

Diagnose and stop a Valkey full-resync loop

Eight steps, all online; step 8 briefly disconnects the replicas on purpose

  1. Confirm the loop on the primary

    Run it twice, a few minutes apart. sync_full and sync_partial_err rising together is the loop.

    valkey-cli -h 10.0.1.10 INFO stats \ | grep -E "^(sync_|client_output)"
  2. Read the reason in the primary log

    "lack of backlog" points to step 4. "output buffer limits" points to step 5. "timedout replica" points to the network or repl-timeout.

    grep -E "lack of backlog|output buffer|timedout" \ /var/log/valkey/valkey.log | tail -20
  3. Measure the write rate and sync duration

    Sample master_repl_offset 60 seconds apart at peak, and read the full sync duration from the replica log.

    valkey-cli -h 10.0.1.10 INFO replication \ | grep master_repl_offset
  4. Raise the backlog on every node

    Write rate times the longest disconnect, plus headroom. Repeat on each replica, then persist with CONFIG REWRITE.

    valkey-cli -h 10.0.1.10 CONFIG SET \ repl-backlog-size 512mb
  5. Raise the replica output buffer limit

    Write rate times full sync duration, plus headroom. Check that the host has the memory first.

    valkey-cli -h 10.0.1.10 CONFIG SET \ client-output-buffer-limit "replica 2gb 1gb 300"
  6. Optionally move the buffer to the replica

    Only on 8.x, 9.0.5 or later, or 9.1.1 or later. Set it on the primary and every replica; it applies from the next sync.

    valkey-cli -h 10.0.1.11 CONFIG SET \ dual-channel-replication-enabled yes
  7. Watch the next full sync finish

    Wait for master_link_status:up and "sync: Finished with success" in the replica log.

    valkey-cli -h 10.0.1.11 INFO replication \ | grep -E "^master_(link_status|sync_)"
  8. Rehearse a disconnect

    This drops every replica of this primary, so pick a quiet time. sync_partial_ok should rise, not sync_full.

    valkey-cli -h 10.0.1.10 CLIENT KILL TYPE replica

Main risk: larger buffers trade a resync loop for memory. If the primary nears its memory limit during the next full sync, set the old limits back and plan more RAM before you try again.

If the rehearsal still produces a full sync, the backlog range in the primary log shows how far short the backlog fell. Each full sync also starts with a fork, which is a latency event on the primary; the Valkey latency spike runbook shows how to read latest_fork_usec.

What do the Valkey 9.2 release candidates add for full syncs?

Everything in this section is from the 9.2 release candidates (9.2.0-rc2, 4 November 2026). Names and defaults can change before 9.2.0 GA, so do not plan production changes around them yet.

  • Replication throttling. repl-throttling-enabled (default no) slows client writes on the primary when a replica's output buffer grows toward its soft limit, so the replica can catch up instead of being cut off (9.2.0-rc1 release notes, #4356). Pull request #4356 lists its INFO fields, including repl_throttle_rate and repl_throttle_total_commands.
  • Stream compression. In rc2, repl-compression (default no) compresses the diskless full sync payload and the ongoing stream, with lz4 or, on builds with Zstandard support, zstd (added in rc2). Set it on both sides; the link uses the strongest codec both support.
  • Forkless full sync. rc2 can serve full syncs from a background-thread snapshot instead of a fork (pull request #4797). It needs forkless-infrastructure-enabled yes at startup and forkless-policy prefer-forkless. It falls back to a fork for dual-channel syncs and for links that need compression.
  • Fewer accidental full syncs. Replicas retry PSYNC when the primary replies -BUSY instead of dropping to the legacy SYNC path (#4140).
  • A sync duration field. last_successful_sync_duration_ms in INFO replication reports how long the replica's last full sync took (#4197). The INFO reference already lists it without a version note; it is not in 9.1.3.

These options pull in different directions: throttling slows writers to protect the link, compression trades CPU for bandwidth, and forkless sync avoids fork copy-on-write memory but does not combine with dual-channel or compression in rc2. Test one change at a time on staging.

Frequently asked questions

What is the default repl-backlog-size in Valkey?

It is 10 MB in Valkey 8.0 and later, including 9.1.3. Before 8.0, the default was 1 MB. The 10 MB default suits light write loads only. Measure how many bytes per second master_repl_offset grows at peak, multiply by the longest disconnect you want to survive, and set that on the primary and every replica.

Why does my Valkey replica keep doing full resyncs?

Usually the backlog is too small for the disconnect, or writes during the full sync exceed the replica output buffer limit, which defaults to 256 MB hard and 64 MB for 60 seconds soft. A cut-off sync leaves an offset the backlog no longer holds, so the retry is another full sync. The primary log names which limit was hit.

Should I enable dual-channel replication in Valkey?

Consider it when full syncs fail on the primary's replica output buffer. It moves buffered writes to the replica, so the replica needs spare memory. Enable it on the primary and every replica, keep repl-diskless-sync on the primary, and on Valkey 9 run 9.0.5, 9.1.1, or later, because earlier 9.x releases fail full syncs of hashes with field TTLs.

How do I check whether a Valkey replica did a partial or a full resync?

On the primary, compare sync_full and sync_partial_ok in INFO stats before and after the reconnect. On the replica, the log shows "Successful partial resynchronization with primary." for a partial resync, or "Full resync from primary:" followed by the replication ID and offset for a full one.

Key takeaways

  • A partial resync needs a known replication ID and an offset still inside the backlog; the primary log says which condition failed.
  • Size repl-backlog-size from the growth rate of master_repl_offset and set it on every node, not only the primary.
  • Size client-output-buffer-limit replica from write rate times full sync duration; the 64 MB for 60 seconds soft limit ends long syncs.
  • Dual-channel replication moves the buffer to the replica; on 9.x, use it only on 9.0.5, 9.1.1, or later.
  • Treat 9.2 throttling, compression, and forkless full sync as release-candidate features until 9.2.0 GA.

Fix Valkey replication with JusDB

JusDB's Valkey high availability team can review your replication settings, measure your write rate and full sync duration, and plan backlog, output buffer, and dual-channel changes that fit the memory you have.

Bring your Valkey versions, your valkey.conf replication settings, INFO output from the primary and one replica, and the log lines from a failed sync. Your team approves every production change.

Share this article

Database engineering notes

Articles like this one, in your inbox. No spam, unsubscribe anytime.

JusDB Team

Official JusDB content team

Keep reading

Moving a Multi-Database Valkey Instance into a 9.x Cluster

Move a Valkey instance that uses SELECT 1 to 15 into a 9.x cluster: keep or remap databases, copy each one, verify counts per database, and keep a way back.

Redis18 minNov 10, 2026
Read

Valkey Keyspace Notifications in Production: Expired Events, hexpired and Cluster Mode

Run Valkey keyspace notifications in production: why expired and hexpired events lag the TTL, how to subscribe on every cluster node, and when a stream is safer.

Redis20 minNov 10, 2026
Read

Valkey GLIDE in Production: AZ-Affinity Reads and Migrating from Legacy Clients

Configure Valkey GLIDE AZ-affinity reads on servers and clients, learn what GLIDE 2.5.3 does not support, and migrate from redis-py, Jedis, ioredis, or go-redis one service at a time.

Redis20 minNov 10, 2026
Read