apache/cassandra · error · ConfigurationException

To be able to set enable_user_defined_functions_threads: fal

Error message

To be able to set enable_user_defined_functions_threads: false you need to set allow_insecure_udfs: true - this is an unsafe configuration and is not recommended.

What it means

Thrown when enable_user_defined_functions_threads is set to false without allow_insecure_udfs: true. Single-threaded UDF execution is only permitted in insecure mode because UDFs can then block or escape the runtime guarantees Cassandra makes; the combination without allow_insecure_udfs is rejected at startup.

Source

Thrown at src/java/org/apache/cassandra/config/DatabaseDescriptor.java:1113

        conf.counter_cache_size = new DataStorageSpec.LongMebibytesBound(counterCacheSizeInMiB);

        // if set to empty/"auto" then use 5% of Heap size
        indexSummaryCapacityInMiB = (conf.index_summary_capacity == null)
                                    ? Math.max(1, (int) (Runtime.getRuntime().totalMemory() * 0.05 / 1024 / 1024))
                                    : conf.index_summary_capacity.toMebibytes();

        if (indexSummaryCapacityInMiB < 0)
            throw new ConfigurationException("index_summary_capacity option was set incorrectly to '"
                                             + conf.index_summary_capacity.toString() + "', it should be a non-negative integer.", false);

        // we need this assignment for the Settings virtual table - CASSANDRA-17735
        conf.index_summary_capacity = new DataStorageSpec.LongMebibytesBound(indexSummaryCapacityInMiB);

        if (conf.user_defined_functions_fail_timeout.toMilliseconds() < conf.user_defined_functions_warn_timeout.toMilliseconds())
            throw new ConfigurationException("user_defined_functions_warn_timeout must less than user_defined_function_fail_timeout", false);

        if (!conf.allow_insecure_udfs && !conf.user_defined_functions_threads_enabled)
            throw new ConfigurationException("To be able to set enable_user_defined_functions_threads: false you need to set allow_insecure_udfs: true - this is an unsafe configuration and is not recommended.");

        if (conf.allow_extra_insecure_udfs)
            logger.warn("Allowing java.lang.System.* access in UDFs is dangerous and not recommended. Set allow_extra_insecure_udfs: false to disable.");

        if (conf.scripted_user_defined_functions_enabled)
            throw new ConfigurationException("JavaScript user-defined functions were removed in CASSANDRA-18252. " +
                                             "Hooks are planned to be introduced as part of CASSANDRA-17280");

        if (conf.commitlog_segment_size.toMebibytes() == 0)
            throw new ConfigurationException("commitlog_segment_size must be positive, but was "
                                             + conf.commitlog_segment_size.toString(), false);
        else if (conf.commitlog_segment_size.toMebibytes() >= 2048)
            throw new ConfigurationException("commitlog_segment_size must be smaller than 2048, but was "
                                             + conf.commitlog_segment_size.toString(), false);

        if (conf.max_mutation_size == null)
            conf.max_mutation_size = new DataStorageSpec.IntKibibytesBound(conf.commitlog_segment_size.toKibibytes() / 2);
        else if (conf.commitlog_segment_size.toKibibytes() < 2 * conf.max_mutation_size.toKibibytes())

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Re-enable UDF threads (user_defined_functions_threads_enabled: true), the recommended configuration.
  2. Or explicitly accept the risk by setting allow_insecure_udfs: true alongside threads: false.
  3. Restart the node after changing either setting.

Example fix

# before
enable_user_defined_functions_threads: false
# after (option A, recommended)
enable_user_defined_functions_threads: true
# after (option B, insecure)
enable_user_defined_functions_threads: false
allow_insecure_udfs: true
Defensive patterns

Strategy: validation

Validate before calling

boolean threads = (boolean) yaml.getOrDefault("user_defined_functions_threads_enabled", true);
boolean insecure = (boolean) yaml.getOrDefault("allow_insecure_udfs", false);
if (!threads && !insecure)
    throw new IllegalArgumentException("Disabling UDF threads requires allow_insecure_udfs: true");

Try / catch

try {
    DatabaseDescriptor.applySimpleConfig();
} catch (ConfigurationException e) {
    if (e.getMessage().contains("enable_user_defined_functions_threads"))
        logger.error("Re-enable UDF threads or set allow_insecure_udfs: true");
}

Prevention

When it happens

Trigger: cassandra.yaml contains enable_user_defined_functions_threads: false and allow_insecure_udfs: false (or unset).

Common situations: Operators trying to reduce UDF thread overhead disable threading; copying old pre-CASSANDRA config samples where the security flag coupling did not exist.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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