apache/cassandra · error · IllegalArgumentException

Can't delete hints for unknown address

Error message

Can't delete hints for unknown address 

What it means

IllegalArgumentException thrown by HintsService.deleteAllHintsForEndpoint when the given target address is unknown to the node — StorageService.getHostIdForEndpoint returns null because no host id is mapped to that endpoint.

Solutions

1. Verify the address with `nodetool status` / system.peers before deleting
2. Use the node's hostId with deleteHintsForHostId instead of the address form
3. If the node was decommissioned, its hints were already removed — nothing to delete
4. Wait for gossip to settle after node restart before issuing the call

Example fix

// before
HintsService.instance.deleteAllHintsForEndpoint(addr);
// after
UUID hostId = StorageService.instance.getHostIdForEndpoint(addr);
if (hostId != null)
    HintsService.instance.deleteAllHintsForEndpoint(addr);
else
    logger.warn("No host id for {}; skipping hints deletion", addr);

UUID hostId = StorageService.instance.getHostIdForEndpoint(target);
if (hostId == null) {
    logger.warn("Unknown endpoint {} for hints deletion; check nodetool status", target);
    return;
}
HintsService.instance.deleteAllHintsForEndpoint(target);

boolean isKnownEndpoint(InetAddressAndPort a) {
    return StorageService.instance.getHostIdForEndpoint(a) != null;
}

try {
    HintsService.instance.deleteAllHintsForEndpoint(target);
} catch (IllegalArgumentException e) {
    logger.warn("Endpoint unknown; skipping hints deletion: {}", e.getMessage());
}

When it happens

Trigger: Calling deleteAllHintsForEndpoint(InetAddressAndPort) with an address that is not in gossip (no hostId mapping): typo'd IP, decommissioned node still in hints but gone from gossip, or called before gossip convergence.

Common situations: Ops scripts cleaning hints for a node that was already removed; nodetool delifthints (deletehints-for-endpoint path) with a stale or mistyped address; calling during node startup before peer host ids are loaded.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Failed to validate a hint for
• Number of commands to display has to be at least 1.
• Tokens may not contain the character " +…
• A CounterId representation is exactly
• a hints file cannot be configured for both compression and…

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

Appendix: source

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

            target = InetAddressAndPort.getByName(address);
        }
        catch (UnknownHostException e)
        {
            throw new IllegalArgumentException(e);
        }
        deleteAllHintsForEndpoint(target);
    }

    /**
     * Deletes all hints for the provided destination. Doesn't make snapshots - should be used with care.
     *
     * @param target inet address of the target node
     */
    public void deleteAllHintsForEndpoint(InetAddressAndPort target)
    {
        UUID hostId = StorageService.instance.getHostIdForEndpoint(target);
        if (hostId == null)
            throw new IllegalArgumentException("Can't delete hints for unknown address " + target);
        catalog.deleteAllHints(hostId);
    }

    /**
     * Cleans up hints-related state after a node with id = hostId left.
     *
     * Dispatcher can not stop itself (isHostAlive() can not start returning false for the leaving host because this
     * method is called by the same thread as gossip, which blocks gossip), so we can't simply wait for
     * completion.
     *
     * We should also flush the buffer if there are any hints for the node there, and close the writer (if any),
     * so that we don't leave any hint files lying around.
     *
     * Once that is done, we can simply delete all hint files and remove the host id from the catalog.
     *
     * The worst that can happen if we don't get everything right is a hints file (or two) remaining undeleted.
     *
     * @param hostId id of the node being excised

View on GitHub (pinned to 88fd0f6a0e)