Library / SDK
twmb/franz-go avatar
twmb/franz-go

It retracted a release and wrote down why

franz-go is a feature complete, pure Go library for Kafka from 0.8.0 through 4.4+. Producing, consuming, transacting, administrating, etc.

3,153 stars327 forksGoBSD-3-Clause

At a glance

What is it?
franz-go is a Kafka client written entirely in Go that implements the wire protocol itself, which is why its dependency list is three compression libraries long. It tracks improvement proposals by number, it will refuse to talk to a topic you deleted and recreated, and one of its published versions is formally retracted in the manifest with a one-line explanation of why.
Who is it for?
franz-go suits a Go service that needs the newer broker features rather than a legacy client, and the reasons are visible in the manifest rather than in a changelog: it implements the protocol rather than wrapping someone else's, and it pins protocol behaviour rather than negotiating loosely. Three things to check.
Can I use it commercially?
Yes. BSD-3-Clause is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 4 days ago.
What is it written in?
Mainly Go, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • twmb/franz-go3,153 ★ · +82
Star history
Repository2026-09-242026-11-15
twmb/franz-go3.1k3.2k

82 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

One published version is retracted, with the reason inline

The module manifest contains a line that almost no Go manifest contains.

It is a retraction directive for one specific released version, and it carries a comment explaining it: that version is actually a breaking change and requires a major version change.

Go supports retracting a published version so that the tooling treats it as something to avoid, and it is meant for exactly this situation: a release that went out, broke compatibility, and should not be picked up by anyone resolving a range. Most projects in that situation either say nothing or delete the tag. This one marks it.

The comment is the more interesting half. It is a maintainer admitting in the manifest that they shipped something incompatible and that the version number did not reflect it.

For a library at version one and above, with a documented promise to match broker behaviour exactly, that is the right response, and it is the strongest signal in this repository about how the project handles its own mistakes. It also means the release list you should trust has one hole in it, marked.

The manifest also pins the raw-protocol sub-module of this same repository, which is worth a note in the next section rather than here.

Four modules, three dependencies, and its own wire protocol

The dependency list is short enough to read in one line of thought: a compression library, an LZ4 library, and one more module from this same repository.

That last one explains the rest. This project builds its own implementation of the Kafka wire protocol, in a sub-module released separately, and the client depends on that module rather than on somebody else's encoder. The readme states the principle directly: written in pure Go, with no wrapper library for a C library and no bindings.

The repository is four Go modules sharing one tree. The main client, the plugins, the raw-protocol package, and the high-level admin package are each released from their own tag so they can move independently.

So the shortness of the dependency list is not minimalism for its own sake; it is what implementing the protocol yourself buys you. The cost is that the client and the protocol module are separately versioned, which is exactly the seam where a version skew would appear, and exactly the kind of thing the retraction above suggests the project watches.

The readme's example dependency block, incidentally, is behind the manifest: it shows an older version of the protocol module than the one the manifest requires.

Feature complete is defined as every improvement proposal

The readme defines its scope with a rule and then demonstrates it by citing proposal numbers.

The rule: if a client improvement proposal exists, this library aims to support it.

The demonstration is in the consumer section, where the balancing strategies are listed with their proposal numbers behind them. Group consumers support the eager balancers, which are named individually, and the cooperative one. On top of that there is optional rack-aware partition assignment and optional server-side balancing, each with its own number. And there is a separate category of consumer for shared queues, also numbered.

The rest of the list is equally specific: exactly-once semantics, idempotent and transactional producers, all four compression algorithms, all four SASL mechanisms, TLS through configurable dialer options, a low-level request function for administration plus a higher-level admin package, hooks for logs and metrics, plug-in metric integrations, and a schema registry client with a convenience encoding type.

Putting proposal numbers in a feature list is a strong claim about what completeness means, and it is checkable by anyone who reads the proposals. It also explains why the client pins protocol versions rather than negotiating loosely, which is the subject of the next section.

It will refuse a topic you deleted and recreated

There is a behaviour here that is unusual enough to be worth reading twice, because it is the library choosing to stop working rather than to keep working.

By default the client produces to and consumes from the first instance of a topic. If you delete a topic and create it again, and the client is able to detect that this happened, the client refuses to produce to or consume from the new instance.

That is a correctness decision. If a client silently followed the topic to its new incarnation, every offset, every transaction state and every exactly-once assumption it holds would be pointing at a different log with the same name. Refusing is the safe answer and the one that preserves the guarantees the rest of the readme advertises.

The operational cost is equally real. A topic recreation during an incident, or as part of a routine reset, will leave running clients refusing traffic until they restart, with an error that says a topic was recreated rather than something that suggests you restart.

Detection depends on the broker being modern enough and using topic identity, so on an older broker the client cannot do this and the protection is simply absent. That dependency on broker capability is stated in the same paragraph, which is the mark of a project that has thought about the failure modes rather than the happy path.

The headline version range hides a second package for old brokers

The feature list says the client covers a very wide span of broker versions. The version-pinning section quietly qualifies it.

code
go get github.com/twmb/franz-go

The client negotiates: on connect it asks the broker which API versions it supports and then uses the newest one each broker allows. There is an option to pin to an exact version instead.

The qualification is this: the request that makes negotiation possible was introduced in one particular broker version. If you are working with anything older than that, the documentation says you must use a separate package for version handling, and to pin the client with the pinning option if you do.

So the range in the feature list is accurate about what the client can speak, and incomplete about what the client can negotiate. Both halves matter, and only one of them is on the front page.

The second qualification is a list of compatible brokers and services that the readme claims support for. One of them is qualified in place: one cloud service does not support producing with compression, and the readme tells you to turn compression off explicitly, with a link to that provider's own troubleshooting page. That is a more useful thing to find in a client's readme than a claim that everything works everywhere.

It ships a fake broker so you can test your own code

The examples directory is where this project's maturity shows, and two of its entries are about testing rather than about the protocol.

There is an example for testing against a fake broker, and a second one for testing against that fake broker together with the language's newer synchronisation-aware testing facilities. Two example sets for the same problem, which suggests the author considers how you test against a client to be part of the client's surface.

That is a real commitment: the fake is part of the library's own packages, so downstream projects can write tests that exercise their producer and consumer code without standing up a broker. For a client library, that is one of the few things that meaningfully changes how easy it is to adopt.

The rest of the examples read like a list of production concerns: consumer group lag monitoring, runtime control of consumers, dead-letter queues, group committing, manual flushing between produce calls, partitioner selection, record formatting, SASL, the schema registry, and transactions. There is also an example for running one goroutine per partition, which is the consumption model you would reach for if you did not want a shared worker pool. The readme's own performance claim is stated the same way: channels and goroutines are avoided where they are not necessary.

An observability example uses the OpenTelemetry plug-in, and the readme notes plug-in metric integrations for the two most common Go choices as well.

The documentation argues about semantics, and the user list has a duplicate

The supplementary documentation is six files, and three of them are about things that are hard rather than things that are easy.

One explains how to issue administration requests. One describes producing and consuming along with the guarantees each mode gives you. One is titled transactions and its parenthetical says it describes the transactions and the safety even in a pre-proposal world, which means it documents what guarantees you get on brokers that predate a particular improvement.

Another is about metrics and logging, and its parenthetical mentions a few thoughts on latency tracking. The last is about how to write tests for your own code that uses the library, which is the same orientation as the fake broker in the previous section: the project is thinking about the person who has to test the code that depends on it.

The user list tells a similar story, and it has a flaw. It is alphabetical and it includes nineteen companies, among them two entries that are the same organisation, one for a stream-processing product and one for its successor project under a different name. So a curated list nobody updates automatically drifts, which is the least surprising thing in this repository and the only thing in it that looks accidental.

Editorial conclusion

franz-go suits a Go service that needs the newer broker features rather than a legacy client, and the reasons are visible in the manifest rather than in a changelog: it implements the protocol rather than wrapping someone else's, and it pins protocol behaviour rather than negotiating loosely. Three things to check. Read the compatibility section properly, because the headline version range hides two caveats, one of which needs a second package for older brokers and one of which is a named cloud service that cannot accept compressed records. Remember that deleting and recreating a topic will make running clients refuse it until they restart, which is correct behaviour and still an operational surprise. And if you are on an old release line, check whether it predates the retraction.

Frequently asked questions

what is franz go

franz-go is a Kafka client library written entirely in Go, with no wrapper around a C library. Its main package produces, consumes, transacts and administers, and it implements the Kafka wire protocol in its own separately released sub-module, which is why its direct dependency list is three compression libraries.

What exactly is Kafka used for?

This repository does not describe the broker; it is the client library. What it covers is the client surface: producing, consuming with or without a consumer group, transactions and exactly-once semantics, eager and cooperative partition balancing with rack-aware or server-side assignment, shared queue consumers, four compression types, TLS, four SASL mechanisms, administration, and a schema registry client.

Can I use Kafka for free?

Not answered here. What the repository does state is that its own code is BSD licensed, and that it works with the Apache broker and with four named compatible services, one of which cannot accept compressed records and needs compression disabled explicitly.

Is franz-go faster than other Go Kafka clients?

It makes no comparison with any other library. Its own performance claim is negative rather than comparative: it avoids channels and goroutines where they are not necessary, and the examples include a per-partition goroutine consuming model for anyone who wants the alternative.

Official sources

  1. Issues
  2. License: BSD-3-Clause
  3. README
  4. twmb/franz-go on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/twmb-franz-go.svg)](https://hysenlabs.com/projects/twmb-franz-go)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/twmb-franz-go.svg)](https://hysenlabs.com/projects/twmb-franz-go)

Was this useful?