sofastack/sofa-jraft: a Java Raft library for multi-group consensus

The gap SOFAJRaft fills for Java services

Consensus is the part of a distributed system that most teams get wrong the first time. SOFAJRaft exists so that a Java service can keep a replicated log consistent across a group of nodes without implementing leader election, log matching or membership changes from scratch. The README describes it as "a production-level, high-performance Java implementation based on the RAFT consistency algorithm that supports MULTI-RAFT-GROUP for high-load, low-latency scenarios." That sentence contains the two things worth noting: it is a library rather than a server, and the multi-group design targets machines that host many small consensus groups rather than one large one.

The audience is narrower than the description suggests. You need a Java service, a state machine you can replay deterministically, and a place to put snapshots. If you want a database with a query interface, SOFAJRaft is the wrong layer. The project does ship an embedded distributed KV storage implementation in the jraft-rheakv module, and the README lists it as a feature, but the core artefact is the consensus library. Teams that treat jraft-core as a drop-in storage engine usually discover the state machine contract the hard way, during the first snapshot transfer.

How the Raft core is organised in the repository

The top-level layout tells you how the project is split: jraft-core holds the consensus implementation, jraft-example holds runnable samples, jraft-extension holds optional pieces, jraft-rheakv holds the KV storage layer, and jraft-test holds test support. That separation matters when you decide what to depend on. A service that only needs the log and election machinery depends on jraft-core; the KV layer is a separate concern with its own module and its own operational shape.

The feature list in the README is effectively a map of the internal machinery. Leader election includes a priority-based semi-deterministic variant, which lets you bias which node wins rather than leaving it purely to the Raft timeout. Log replication supports a replication pipeline, so followers can be fed without waiting for a full round trip per entry. Reads can be served as linearizable through ReadIndex or LeaseRead, which are two different trade-offs between coordinating with the leader and trusting a time window. Membership management covers adding, removing and replacing nodes, and there is a transfer-leader mechanism intended for reboots and load balancing.

The failure-handling claims are the part worth reading carefully. The README states that minority failure does not affect overall availability, which is standard Raft, and that a manual recovery cluster is available for majority failure. That second item is not automatic: it is a procedure you invoke when you have lost quorum, and it is the kind of operation where a mistake produces split brain rather than an error message. The README also lists symmetric and asymmetric network partition tolerance, and notes that the project passed a Jepsen consistency verification test. Jepsen results describe the version and configuration that were tested, not every deployment you will build on top of the library.

Building SOFAJRaft and running a first counter

The build requirements are stated plainly in the README: JDK 8+ and Maven 3.2.5+. The repository is a multi-module Maven build rooted at pom.xml, so the first build resolves dependencies for jraft-core, jraft-example, jraft-extension, jraft-rheakv and jraft-test. Before running anything, read the User Guide and the Counter Example Details pages that the README links to, since those are where the project explains the intended usage path.

The README does not print a build command of its own. It states the compile requirement and points to the documents, so the practical route is to clone the repository and run Maven at the root, then read the counter example in jraft-example. For a service that consumes the library rather than the source tree, the artefact is published under the com.alipay.sofa group on Maven Central, which the README surfaces through its Maven Central badge; the module names visible in the repository layout are jraft-core, jraft-rheakv and the rest.

The first real use is the counter example. The README links to Counter Example Details, and jraft-example exists in the repository, so the intended path is: read the counter example, run it, then replace its state machine with yours. That example is where you see the shape of the contract, namely a state machine that applies committed log entries and produces snapshots. The README does not document a rollback procedure for a failed snapshot install, so plan for that case yourself rather than expecting the library to cover it.

What the state machine contract costs you

The library handles consensus; it does not handle your data. Every command that reaches the log has to be applied to a state machine, and that state machine has to produce the same result on every node and after every restart. Any nondeterminism, such as reading the local clock, iterating a hash map whose order varies, or depending on an external service during apply, will eventually diverge the replicas. Raft will faithfully replicate your bug.

Snapshots are the second half of that contract. The README lists snapshot and log compaction as a feature, which means the library will ask your state machine to serialize itself and will later ask it to load that serialization on a follower that has fallen too far behind. How large that snapshot is, how long it takes to transfer, and what happens to your service while it transfers are all your decisions. This is the point where a design that looked like a thin library turns into an operational commitment.

The multi-Raft-group feature is the clearest example of a trade-off rather than a free win. Running many groups per process lets you place many small replicated logs on the same machine, which suits high-load, low-latency scenarios with many independent shards. It also means one process now hosts many leaders and followers, so a single garbage collection pause or thread pool saturation can disturb several groups at once. Isolation between groups is logical, not physical.

When SOFAJRaft is the wrong tool

If you want a distributed database, SOFAJRaft is a component, not an answer. There is no query language, no client protocol, and no schema. The jraft-rheakv module is described as an embedded distributed KV storage implementation, which is closer to a storage layer than to a database service, and the README does not present it as a general-purpose data store with the operational surface of one.

If your team has no experience operating a Raft group, the manual recovery path for majority failure is the feature to think about before adopting, not after. Losing quorum is a real event, and the README says a manual recovery cluster is available for that case, which means a human runs a procedure. That is an honest design choice, since automatic recovery from quorum loss is where consensus systems tend to invent data, but it is also a runbook you have to own.

If your workload is a single small configuration store with low write volume, a full Raft group per service may be more machinery than the problem needs, and a simpler replicated store or an external coordination service will cost less to run. SOFAJRaft earns its place when the replicated log is central to your service and you need control over the state machine, not when you need a key-value endpoint.

How SOFAJRaft differs from etcd and from braft

The nearest alternative most teams consider is etcd, which implements the same Raft algorithm but ships as a standalone server with a gRPC API and a key-value model. The difference in approach is where the state machine lives. With etcd, the state machine is fixed: you get a key-value store and you build on top of it over the network. With SOFAJRaft, the state machine is yours and it runs in your process, so a committed entry can update an in-memory index, a custom file format, or anything else, without a network hop or a serialization boundary. That is more control and more responsibility at the same time. etcd also brings its own operational tooling, which SOFAJRaft does not attempt to replace.

Within Java, the other reference point is the project's own lineage. The README states that SOFAJRaft was ported from Baidu's braft with optimising and improvement, and thanks the braft team. braft is a C++ implementation, so the practical difference for a Java shop is the runtime and the ecosystem, not the algorithm. The README also notes that SOFAJRaft directly references some Apache-2.0 licensed code, including HashedWheelTimer from Netty and Netty's Pipeline design, and efficient UTF8 string encoding and decoding from Protobuf. Those are implementation details you inherit, and they are disclosed rather than hidden.

Licence, maintenance and upgrade cost

SOFAJRaft is licensed under Apache License 2.0, and the README states that the third-party components it relies on are also Apache License 2.0, as is the directly referenced code from Netty and Protobuf. For most commercial use that is a permissive arrangement, but the licence text is the authority and this is not legal advice; if you redistribute the library or modify referenced code, have your own review done.

On maintenance, the repository is not archived, and the last push was on 2026-06-16. The release history is uneven in cadence: v1.4.1 on 2026-06-15, v1.4.0 on 2025-07-14, and 1.3.15.bugfix on 2024-08-12. That pattern suggests a project that ships when there is something to ship rather than on a schedule, so pin an explicit version rather than tracking a moving target.

Upgrade cost is dominated by your state machine, not by the library. A new release can change how snapshots are requested or how membership operations are sequenced, and those changes land on code you wrote. The README points to a Release Notes page on the project site, and reading it before bumping a version is cheaper than discovering a behavioural change during a leader transfer in production.

Editorial conclusion

Adopt SOFAJRaft when you are building a Java service that needs a replicated log and you are prepared to implement a state machine plus snapshot handling yourself; the repository separates jraft-core, jraft-rheakv and jraft-example, so start from the counter example before touching core. Do not adopt it if you want a finished distributed database with a query language, or if your team cannot operate a Raft group through leader changes and snapshot transfers. Before committing, verify three things: that your state machine replays deterministically across restarts, how snapshots will be stored and shipped, and which release you are pinning, since v1.4.1 shipped on 2026-06-15 and the last push to master was on 2026-06-16.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. sofastack/sofa-jraft on GitHub