apache/cassandra · error · IllegalStateException

HintsService is shut down and can't accept new hints

Error message

HintsService is shut down and can't accept new hints

What it means

IllegalStateException thrown by HintsService.write when hints are being written after the service has been shut down. Once isShutDown is set (during node shutdown), the write path refuses new hints to avoid writing after resources were released.

Source

Thrown at src/java/org/apache/cassandra/hints/HintsService.java:190

        return builder.build();
    }

    public void registerMBean()
    {
        MBeanWrapper.instance.registerMBean(this, MBEAN_NAME);
    }

    /**
     * Write a hint for a iterable of nodes.
     *
     * @param hostIds host ids of the hint's target nodes
     * @param hint the hint to store
     */
    public void write(Collection<UUID> hostIds, Hint hint)
    {
        if (isShutDown)
            throw new IllegalStateException("HintsService is shut down and can't accept new hints");

        // we have to make sure that the HintsStore instances get properly initialized - otherwise dispatch will not trigger
        catalog.maybeLoadStores(hostIds);

        bufferPool.write(hostIds, hint);

        StorageMetrics.totalHints.inc(hostIds.size());
    }

    /**
     * Write a hint for a single node.
     *
     * @param hostId host id of the hint's target node
     * @param hint the hint to store
     */
    public void write(UUID hostId, Hint hint)
    {
        write(Collections.singleton(hostId), hint);

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Ensure hint writes stop before shutdown is initiated (drain writes first)
2. Guard calls with a lifecycle check (catch IllegalStateException and drop the hint — hints are best-effort)
3. In tests, shut down HintsService last, after all producers complete
4. If hit on a live node unexpectedly, check for a shutdown/restart bug in node lifecycle (report with logs)

Example fix

// before
HintsService.instance.write(hostIds, hint);
// after
try {
    HintsService.instance.write(hostIds, hint);
} catch (IllegalStateException e) {
    // hints are best-effort; dropping during shutdown is acceptable
}

// producer-side check before writing
if (HintsService.instance.isShutDown()) { logger.debug("Dropping hint: service shut down"); return; }

boolean canWriteHints() { return !HintsService.instance.isShutDown(); }

try {
    HintsService.instance.write(hostIds, hint);
} catch (IllegalStateException e) {
    logger.debug("Hints service shut down; dropping hint (best-effort)");
}

When it happens

Trigger: Calling HintsService.write() (directly or via writeForAllReplicas) after HintsService.shutdownBlocking() — e.g. custom code writing hints during shutdown, or race between mutation handling and shutdown.

Common situations: Batches/batchlog writing hints concurrently with node decommission/stop; plugin or test code calling the hints API late in the lifecycle.

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

• HintsService is shut down and cannot be restarted
• HintsService has already been shut down
• Scheduler has shut down.
• Hint dispatch was interrupted
• Some hints were not written before shutdown. This is not su

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