apache/cassandra · error · IllegalStateException

Attempted to reference an already released SharedByteBuffer

Error message

Attempted to reference an already released SharedByteBuffer

What it means

ShareableBytes wraps a buffer with a reference count; doRetain() increments that count in a CAS loop. If the count has already reached the RELEASED sentinel (-1), the buffer can no longer be referenced and retain() throws IllegalStateException.

Solutions

Fix ownership so each consumer retains before the releaser releases (retain-then-use ordering)
Check bytes.isReleased() before retaining in deferred/async callbacks
Remove the duplicate release that frees the buffer while still in use

Example fix

// before
releaseShared(buffer);
consumer.accept(shared); // may retain after release
// after
shared.retain(); // take a reference before releasing producer's copy
releaseShared(buffer);
consumer.accept(shared);

Defensive patterns

Strategy: type-guard

Validate before calling

if (shared.isReleased()) { /* do not use */ }

Type guard

boolean usable(ShareableBytes b) { return b != null && !b.isReleased(); }

Try / catch

try { shared.retain(); } catch (IllegalStateException e) { log.debug("Buffer already released; dropping reference"); }

Prevention

Retain before handing a buffer to async consumers
Establish a single owner responsible for the final release
Check isReleased() in deferred callbacks

When it happens

Trigger: Calling bytes.retain() (or sharing the buffer) after bytes.release() has dropped the final reference, e.g. retaining a frame buffer in a callback that runs after the connection already released it.

Common situations: Async messaging pipelines where a read handler keeps a reference to SharedBytes past the point the connection handler releases it; double-release then retain; races between frame consumer and connection teardown.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/de384e1c17a7d230. Report an issue: GitHub.

Appendix: source

Thrown at src/java/org/apache/cassandra/net/ShareableBytes.java:113

    private ShareableBytes retain()
    {
        owner.doRetain();
        return this;
    }

    private void doRetain()
    {
        int count = this.count;
        if (count < 0)
        {
            countUpdater.lazySet(this, count - 1);
            return;
        }

        while (true)
        {
            if (count == RELEASED)
                throw new IllegalStateException("Attempted to reference an already released SharedByteBuffer");

            if (countUpdater.compareAndSet(this, count, count + 1))
                return;

            count = this.count;
        }
    }

    public void release()
    {
        owner.doRelease();
    }

    private void doRelease()
    {
        int count = this.count;

        if (count < 0)

View on GitHub (pinned to 88fd0f6a0e)