nodetool getguardrailsconfig

Cassandra 5.0+

This command is available in Cassandra 5.0 and later.

Displays the current guardrails configuration.

Synopsis

nodetool [connection_options] getguardrailsconfig [options] [guardrail_name]

See connection options for connection options.

Options

Option	Description
`-c, --category <category>`	Filter output by category: `values`, `thresholds`, `flags`, `others`
`--expand`	Show expanded details for each guardrail

Arguments

Argument	Description
`guardrail_name`	Optional. Show configuration for a specific guardrail only

Description

nodetool getguardrailsconfig displays the current guardrails configuration for the node. Guardrails are protective limits that prevent potentially harmful operations in Cassandra, such as creating too many tables, using dangerous query patterns, or exceeding safe data sizes.

Guardrails help maintain cluster stability by enforcing best practices and preventing operations that could lead to performance degradation or outages.

Output Categories

The guardrails are organized into the following categories:

Category	Description
`values`	Numeric limit values (warn/fail thresholds)
`thresholds`	Size and count thresholds
`flags`	Boolean enable/disable settings
`others`	Other guardrail configurations

Table Guardrails

Setting	Description
`tables_warn_threshold`	Warning when table count exceeds this
`tables_fail_threshold`	Reject operations when table count exceeds this
`columns_per_table_warn_threshold`	Warning for columns per table
`columns_per_table_fail_threshold`	Rejection for columns per table

Query Guardrails

Setting	Description
`page_size_warn_threshold`	Warning for large page sizes
`page_size_fail_threshold`	Rejection for excessive page sizes
`in_select_cartesian_product_warn_threshold`	Warning for IN clause combinations
`in_select_cartesian_product_fail_threshold`	Rejection for IN clause combinations

Collection Guardrails

Setting	Description
`collection_size_warn_threshold`	Warning for large collections
`collection_size_fail_threshold`	Rejection for excessive collections
`items_per_collection_warn_threshold`	Warning for collection item count
`items_per_collection_fail_threshold`	Rejection for collection item count

Partition Guardrails

Setting	Description
`partition_keys_in_select_warn_threshold`	Warning for partition keys in SELECT
`partition_keys_in_select_fail_threshold`	Rejection for partition keys in SELECT

Examples

Basic Usage

nodetool getguardrailsconfig

Sample output:

Guardrails Configuration:
  Tables:
    Warn Threshold: 100
    Fail Threshold: 150
  Columns Per Table:
    Warn Threshold: 50
    Fail Threshold: 100
  Page Size:
    Warn Threshold: 5000
    Fail Threshold: 10000
  Collection Size:
    Warn Threshold: 65536
    Fail Threshold: -1 (disabled)
  ...

When to Use

Review Cluster Protection Settings

# Check current guardrail configuration
nodetool getguardrailsconfig

Review guardrails when:

Planning schema changes
Debugging query rejections
Auditing cluster configuration
Onboarding new development teams

Before Schema Operations

# Check limits before creating tables
nodetool getguardrailsconfig | grep -i table

Verify guardrail limits before operations that might be affected.

Troubleshooting Query Failures

# Check if queries are hitting guardrails
nodetool getguardrailsconfig

When queries fail with guardrail errors, check current thresholds to understand the limits.

Guardrail Types

Warn vs Fail Thresholds

Warn threshold: Logs a warning but allows the operation
Fail threshold: Rejects the operation with an error

A value of -1 typically indicates the guardrail is disabled.

Best Practices

Guardrail Strategy

Use warn thresholds - Enable warnings before hard failures to catch issues early
Document limits - Ensure developers understand guardrail boundaries
Monitor warnings - Set up alerts for guardrail warnings
Review periodically - Adjust thresholds based on operational experience

When to Adjust Guardrails

Consider modifying guardrails when:

Legitimate use cases exceed defaults
Stricter controls are needed for multi-tenant environments
Specific applications have validated requirements

Guardrail Considerations

Guardrails exist to protect cluster stability
Relaxing limits should be done cautiously
Test thoroughly before changing production guardrails
Some guardrails affect existing data operations, not just new writes

Guardrails can also be configured in cassandra.yaml:

guardrails:
    tables_warn_threshold: 100
    tables_fail_threshold: 150
    columns_per_table_warn_threshold: 50
    columns_per_table_fail_threshold: 100
    # ... additional settings

Command	Relationship
setguardrailsconfig	Modify guardrail settings
describecluster	Cluster configuration overview
info	Node information