apache/cassandra · error · InvalidRequestException

NODE_LOCAL consistency level is highly dangerous and should…

Error message

NODE_LOCAL consistency level is highly dangerous and should be used only for debugging purposes

What it means

processNodeLocalStatement() executes statements with NODE_LOCAL consistency, a debugging-only mechanism that reads/writes on the local node without normal distributed guarantees. It is gated by the enable_nodelocal_queries system property flag; when disabled, any NODE_LOCAL query is rejected outright.

Solutions

Start Cassandra with -Dcassandra.enable_nodelocal_queries=true (debug environments only).
Use a normal consistency level (e.g. LOCAL_QUORUM) instead of NODE_LOCAL in production code.

Example fix

// before (jvm opts)
cassandra.enable_nodelocal_queries unset
// after
JVM_OPTS="$JVM_OPTS -Dcassandra.enable_nodelocal_queries=true"

Defensive patterns

Strategy: validation

Validate before calling

if (cl == ConsistencyLevel.NODE_LOCAL && !Boolean.getBoolean("cassandra.enable_nodelocal_queries")) throw new IllegalStateException("NODE_LOCAL requires -Dcassandra.enable_nodelocal_queries=true");

Try / catch

try { session.execute(stmt.setConsistencyLevel(NODE_LOCAL)); } catch (InvalidRequestException e) { if (e.getMessage().contains("NODE_LOCAL consistency level is highly dangerous")) { /* enable flag or use standard CL */ } }

Prevention

Use NODE_LOCAL only in debug/test environments
Set the flag explicitly in test JVM options
Default code to standard consistency levels

When it happens

Trigger: Sending a query with consistency level NODE_LOCAL while -Dcassandra.enable_nodelocal_queries=true (or the corresponding Config flag) is not set.

Common situations: Internal tooling or tests using NODE_LOCAL forgetting to set the flag; accidental NODE_LOCAL from a misconfigured driver on a debug feature.

Related errors

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

Appendix: source

Thrown at src/java/org/apache/cassandra/cql3/QueryProcessor.java:320

    public ResultMessage processStatement(CQLStatement statement, QueryState queryState, QueryOptions options, Dispatcher.RequestTime requestTime)
    throws RequestExecutionException, RequestValidationException
    {
        logger.trace("Process {} @CL.{}", statement, options.getConsistency());
        ClientState clientState = queryState.getClientState();
        statement.authorize(clientState);
        statement.validate(clientState);

        ResultMessage result = options.getConsistency() == ConsistencyLevel.NODE_LOCAL
                             ? processNodeLocalStatement(statement, queryState, options)
                             : statement.execute(queryState, options, requestTime);

        return result == null ? new ResultMessage.Void() : result;
    }

    private ResultMessage processNodeLocalStatement(CQLStatement statement, QueryState queryState, QueryOptions options)
    {
        if (!ENABLE_NODELOCAL_QUERIES.getBoolean())
            throw new InvalidRequestException("NODE_LOCAL consistency level is highly dangerous and should be used only for debugging purposes");

        if (statement instanceof BatchStatement || statement instanceof ModificationStatement)
            return processNodeLocalWrite(statement, queryState, options);
        else if (statement instanceof SelectStatement)
            return processNodeLocalSelect((SelectStatement) statement, queryState, options);
        else if (statement instanceof TransactionStatement)
            return statement.executeLocally(queryState, options);
        else
            throw new InvalidRequestException("NODE_LOCAL consistency level can only be used with BATCH, UPDATE, INSERT, DELETE, and SELECT statements");
    }

    private ResultMessage processNodeLocalWrite(CQLStatement statement, QueryState queryState, QueryOptions options)
    {
        ClientRequestMetrics levelMetrics = ClientRequestsMetricsHolder.writeMetricsForLevel(ConsistencyLevel.NODE_LOCAL);
        ClientRequestMetrics globalMetrics = ClientRequestsMetricsHolder.writeMetrics;

        long startTime = nanoTime();
        try

View on GitHub (pinned to 88fd0f6a0e)