Skip to content

RATIS-2605. Avoid advancing matchIndex from heartbeat AppendEntries success#1519

Merged
szetszwo merged 1 commit into
apache:masterfrom
FMX:fix-ratis-2605
Jul 14, 2026
Merged

RATIS-2605. Avoid advancing matchIndex from heartbeat AppendEntries success#1519
szetszwo merged 1 commit into
apache:masterfrom
FMX:fix-ratis-2605

Conversation

@FMX

@FMX FMX commented Jul 14, 2026

Copy link
Copy Markdown
Contributor

What changes were proposed in this pull request?

This patch fixes leader-side AppendEntries success handling for heartbeat requests.

A follower returns its local nextIndex for successful heartbeat AppendEntries replies. That value describes the follower's local log tail, but it does not prove that all entries
up to nextIndex - 1 match the leader's log. If the follower has a divergent uncommitted tail from an old leader, trusting the heartbeat reply nextIndex may incorrectly advance
the leader-side matchIndex.

Once matchIndex is polluted, later INCONSISTENCY handling can use matchIndex + 1 as a lower bound and prevent nextIndex from backing off to the real common prefix.

This patch preserves the AppendEntries request metadata together with the reply. For successful heartbeat replies, the leader advances only to request.previousLog.index + 1. For
successful append replies, the existing behavior is preserved and reply.nextIndex is still used.

Unit tests are added for:

  1. Heartbeat SUCCESS with previousLog advances only to previousLog.index + 1.
  2. Heartbeat SUCCESS without previousLog does not advance matchIndex.
  3. Append SUCCESS still advances using reply.nextIndex.

What is the link to the Apache JIRA

https://issues.apache.org/jira/browse/RATIS-2605

How was this patch tested?

./mvnw -pl ratis-server -am -Dtest=TestLogAppenderDefault test

  A follower returns its local nextIndex for successful heartbeat
  AppendEntries replies.  This value describes the follower's local log tail,
  but it does not prove that all entries up to nextIndex - 1 match the leader's
  log.

  If a follower has a divergent uncommitted tail from an old leader, trusting the
  heartbeat reply nextIndex may incorrectly advance the leader-side matchIndex.
  Later INCONSISTENCY handling uses matchIndex + 1 as a lower bound, so the
  polluted matchIndex can prevent nextIndex from backing off to the real common
  prefix.

  Track the AppendEntries request metadata together with the reply.  For
  successful heartbeat replies, advance only to request.previousLog.index + 1.
  For successful append replies, continue using reply.nextIndex since appended
  entries prove the returned match point.

  Add unit tests for heartbeat success with and without previousLog, and verify
  that append success still uses reply.nextIndex.

@szetszwo szetszwo left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@FMX , thanks a lot for reporting and fixing the bug!

+1 the change looks good.

@szetszwo szetszwo merged commit 6aafce5 into apache:master Jul 14, 2026
16 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants