apache/cassandra · error · IllegalArgumentException

Only -1 (undefined) and positive values are allowed; given

Error message

Only -1 (undefined) and positive values are allowed; given %d

What it means

OptionaldPositiveInt models an int that is either -1 (undefined) or any value >= 1; 0 and values < -1 are meaningless for the settings it backs. The constructor throws IllegalArgumentException for any value outside {-1} ∪ [1, Integer.MAX_VALUE].

Solutions

1. Use -1 to mean undefined/disabled.
2. Use a positive integer (>= 1) for a defined value.
3. Fix config/code paths that produce 0 or negative values before constructing.

Example fix

// before
maxValue = new OptionaldPositiveInt(0);
// after
maxValue = new OptionaldPositiveInt(-1); // undefined

if (!(v == -1 || v >= 1)) throw new IllegalArgumentException("expected -1 or positive, got " + v);

static boolean isValidOptionalPositive(int v) { return v == -1 || v >= 1; }

try { new OptionaldPositiveInt(v); } catch (IllegalArgumentException e) { LOG.error("bad optional-positive int: {}", e.getMessage()); }

When it happens

Trigger: Constructing OptionaldPositiveInt(0) or with a negative value other than -1, typically from config parsing where a field was set to 0 or a negative number other than the -1 sentinel.

Common situations: Setting a config field like a max threshold to 0 thinking 0 means 'disabled'; computing values programmatically that can go negative; misunderstanding that -1, not 0, is the 'undefined' sentinel.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• accord.working_set_size option was set incorrectly to
• chunk_length_in_kb must be a power of 2
• concurrent_counter_writes must be at least 2, but was
• concurrent_reads must be at least 2, but was
• Concurrent reads must be non-negative

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

Appendix: source

Thrown at src/java/org/apache/cassandra/config/OptionaldPositiveInt.java:34

 * limitations under the License.
 */

package org.apache.cassandra.config;

import java.util.Objects;
import java.util.function.IntSupplier;

public class OptionaldPositiveInt
{
    public static final int UNDEFINED_VALUE = -1;
    public static final OptionaldPositiveInt UNDEFINED = new OptionaldPositiveInt(UNDEFINED_VALUE);

    private final int value;

    public OptionaldPositiveInt(int value)
    {
        if (!(value == -1 || value >= 1))
            throw new IllegalArgumentException(String.format("Only -1 (undefined) and positive values are allowed; given %d", value));
        this.value = value;
    }

    public boolean isDefined()
    {
        return value != UNDEFINED_VALUE;
    }

    public int or(int defaultValue)
    {
        return value == UNDEFINED_VALUE ? defaultValue : value;
    }

    public int or(IntSupplier defaultValue)
    {
        return value == UNDEFINED_VALUE ? defaultValue.getAsInt() : value;
    }

View on GitHub (pinned to 88fd0f6a0e)