apache/cassandra · error · RuntimeException

Unable to initialise %s

Error message

Unable to initialise %s

What it means

NativeSSTableLoaderClient.init() connects to the target cluster via the native protocol, fetches schema metadata (tables and materialized views) for a keyspace, and wraps any failure in this RuntimeException. It signals that the SSTable loader client could not initialize its in-memory schema cache. The original exception is preserved as the cause.

Source

Thrown at tools/sstableloader/src/org/apache/cassandra/utils/NativeSSTableLoaderClient.java:124

                                                 tokenFactory.fromString(tokenRange.getEnd().getValue().toString()));
                for (Host endpoint : endpoints)
                {
                    int broadcastPort = endpoint.getBroadcastSocketAddress().getPort();
                    // use port from broadcast address if set.
                    int portToUse = broadcastPort != 0 ? broadcastPort : storagePort;
                    addRangeForEndpoint(range, InetAddressAndPort.getByNameOverrideDefaults(endpoint.getAddress().getHostAddress(), portToUse));
                }
            }

            Types types = fetchTypes(keyspace, session);

            tables.putAll(fetchTables(keyspace, session, partitioner, types));
            // We only need the TableMetadata for the views, so we only load that.
            tables.putAll(fetchViews(keyspace, session, partitioner, types));
        }
        catch (Exception e)
        {
            throw new RuntimeException("Unable to initialise " + NativeSSTableLoaderClient.class.getName(), e);
        }
    }

    public TableMetadataRef getTableMetadata(String tableName)
    {
        return tables.get(tableName);
    }

    @Override
    public void setTableMetadata(TableMetadataRef cfm)
    {
        tables.put(cfm.name, cfm);
    }

    private static Types fetchTypes(String keyspace, Session session)
    {
        String query = String.format("SELECT * FROM %s.%s WHERE keyspace_name = ?", SchemaConstants.SCHEMA_KEYSPACE_NAME, SchemaKeyspaceTables.TYPES);

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Verify the cluster is reachable at the given hosts/port (cqlsh connection test).
2. Check username/password and authenticator settings on the cluster.
3. Confirm the keyspace exists (DESCRIBE KEYSPACES in cqlsh).
4. Inspect the chained cause exception for the root failure (connection refused, auth error, etc.).
5. Check driver/protocol version compatibility between the tool and the server.

Example fix

// before
client.init(hosts, port, null);
// after
try { client.init(hosts, port, null); }
catch (RuntimeException e) { System.err.println("Init failed: " + e.getCause()); throw e; }

// verify connectivity first
try (com.datastax.driver.core.Cluster c = com.datastax.driver.core.Cluster.builder().addContactPoints(hosts).withPort(port).build()) {
    boolean ksExists = c.getMetadata().getKeyspace(keyspace) != null;
    if (!ksExists) throw new IllegalStateException("keyspace missing: " + keyspace);
}

try { client.init(hosts, port, authProvider); }
catch (RuntimeException e) {
    // cause holds the real failure: IOException (unreachable), auth, protocol mismatch
    throw new IllegalStateException("Loader init failed: " + e.getCause(), e);
}

When it happens

Trigger: Calling NativeSSTableLoaderClient.init(hosts, port) when the cluster is unreachable, authentication fails, the keyspace does not exist, or schema fetch queries fail (e.g. protocol/serialization mismatch between client and server versions).

Common situations: sstableloader run against a cluster that is down or firewalled; wrong credentials for an authenticated cluster; typo in keyspace name; loading SSTables of a newer version than the target node supports.

Related errors

• Streaming to the following hosts failed:
• Configured ${configName} "${intf}" could not be found
• Configured ${configName} "${intf}" was found, but had no add
• Configured ${configName} "${intf}" caused an exception
• Set listen_address OR listen_interface, not both

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