apache/cassandra · error · IllegalStateException

Hot reloading functionality has not been initialized.

Error message

Hot reloading functionality has not been initialized.

What it means

Cassandra's SSLFactory supports hot reloading of TLS certificates, but this must first be enabled by calling initHotReloading(). checkCertFilesForHotReloading() performs a forced revalidation of cached SSL contexts, and throws IllegalStateException when the hot reloading machinery was never initialized, because there is nothing registered to check or reload.

Solutions

Call SSLFactory.initHotReloading(ServerEncryptionOptions, EncryptionOptions, boolean) once at startup before any checkCertFilesForHotReloading() call.
If you rely on forced reloads (e.g. after rotating certs), ensure your node's configuration path initializes hot reloading (enabled encrypted transports trigger it).
Guard the call: only invoke checkCertFilesForHotReloading when hot reloading is known to be initialized in this JVM.
In tests, call initHotReloading in setup before exercising reload checks.

Example fix

// before
SSLFactory.checkCertFilesForHotReloading();

// after
SSLFactory.initHotReloading(serverEncryptionOptions, clientEncryptionOptions, true);
SSLFactory.checkCertFilesForHotReloading();

Defensive patterns

Strategy: validation

Validate before calling

// Java: check initialization before forcing a reload
java.lang.reflect.Field f = SSLFactory.class.getDeclaredField("isHotReloadingInitialized");
f.setAccessible(true);
if (!f.getBoolean(null)) {
    SSLFactory.initHotReloading(serverEncryptionOptions, clientEncryptionOptions, true);
}
SSLFactory.checkCertFilesForHotReloading();

Prevention

Always call initHotReloading during node startup when encrypted transports are used
Wrap forced reload calls in a helper that initializes on first use
In tests, initialize hot reloading in the setup phase

When it happens

Trigger: Calling SSLFactory.checkCertFilesForHotReloading() (directly or via tooling/JMX that forces a certificate check) when initHotReloading(ServerEncryptionOptions, EncryptionOptions, boolean) has not been called for the process, i.e. the static isHotReloadingInitialized flag is still false.

Common situations: Operators invoking a forced cert recheck on a node started without ssl_storage_encryption/options requiring hot reload; custom code or scripts calling checkCertFilesForHotReloading at startup before initHotReloading; test harnesses exercising reload paths without the init call; config where hot reloading is disabled so initHotReloading is skipped.

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/6217d34f7265e032. Report an issue: GitHub.

Appendix: source

Thrown at src/java/org/apache/cassandra/security/SSLFactory.java:187

     * Create a Netty {@link SslContext} with a supplied cipherFilter
     */
    static SslContext createNettySslContext(EncryptionOptions options, EncryptionOptions.ClientEncryptionOptions.ClientAuth clientAuth,
                                            SocketType socketType, CipherSuiteFilter cipherFilter) throws IOException
    {
        return options.sslContextFactoryInstance.createNettySslContext(clientAuth, socketType,
                                                                       cipherFilter);
    }

    /**
     * Performs a lightweight check whether the certificate files have been refreshed.
     *
     * @throws IllegalStateException if {@link #initHotReloading(EncryptionOptions.ServerEncryptionOptions, EncryptionOptions, boolean)}
     *                               is not called first
     */
    public static void checkCertFilesForHotReloading()
    {
        if (!isHotReloadingInitialized)
            throw new IllegalStateException("Hot reloading functionality has not been initialized.");
        checkCachedContextsForReload(false);
    }

    /**
     * Forces revalidation and loading of SSL certifcates if valid
     */
    public static void forceCheckCertFiles()
    {
        checkCachedContextsForReload(true);
    }

    private static void checkCachedContextsForReload(boolean forceReload)
    {
        List<CacheKey> keysToCheck = new ArrayList<>(Collections.list(cachedSslContexts.keys()));
        while (!keysToCheck.isEmpty())
        {
            CacheKey key = keysToCheck.remove(keysToCheck.size()-1);
            final EncryptionOptions opts = key.encryptionOptions;

View on GitHub (pinned to 88fd0f6a0e)