What causes "value must be non-negative" in apache/cassandra?

Validate the value is >= 0 before calling the function; clamp or correct negative values.

apache/cassandra · error · InvalidRequestException

value must be non-negative

Error message

value must be non-negative

What it means

Thrown by FormatFcts.validateAndGetValue when the numeric argument to a time-formatting function is negative. These functions expect a non-negative epoch/timestamp-like value, and negative inputs are rejected with InvalidRequestException.

Source

Thrown at src/java/org/apache/cassandra/cql3/functions/FormatFcts.java:86

    {
        return decimalFormat.format(value);
    }

    public static void addFunctionsTo(NativeFunctions functions)
    {
        functions.add(FormatBytesFct.factory());
        functions.add(FormatTimeFct.factory());
    }

    private static long validateAndGetValue(Arguments arguments)
    {
        if (arguments.containsNulls())
            throw new InvalidRequestException("none of the arguments may be null");

        long value = getValue(arguments);

        if (value < 0)
            throw new InvalidRequestException("value must be non-negative");

        return value;
    }

    private static long getValue(Arguments arguments)
    {
        Optional<String> maybeString = getAsString(arguments, 0);

        if (maybeString.isPresent())
        {
            try
            {
                return Long.parseLong(maybeString.get());
            }
            catch (Exception ex)
            {
                throw new InvalidRequestException("unable to convert string '" + maybeString.get() + "' to a value of type long");
            }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Validate the value is >= 0 before calling the function; clamp or correct negative values.
Fix the upstream computation producing the negative timestamp (ordering of subtraction, unit conversion).
If pre-epoch dates are legitimate, use a function/type that supports them rather than these format functions.

Example fix

// before: SELECT formatDate(-1000); -- rejected
// after
SELECT formatDate(max(value, 0)); -- clamp, or fix the source value

Defensive patterns

Strategy: validation

Validate before calling

// Java/CQL: reject or clamp negatives before formatting
if (epochMillis < 0) throw new IllegalArgumentException("timestamp must be non-negative");
// CQL: SELECT formatDate(CASE WHEN v < 0 THEN 0 ELSE v END) ...

Try / catch

catch (InvalidRequestException e) { if (e.getMessage().contains("value must be non-negative")) { log.warn("negative value passed to format function"); } }

Prevention

Validate epoch values at ingestion time.
Check subtraction order when computing durations/deltas.
Handle pre-1970 dates with an explicit type, not epoch math.

When it happens

Trigger: Calling a format function with a negative long, typically an epoch-millis/epoch-second value computed from bad data, clock skew before epoch, or arithmetic underflow.

Common situations: Pre-1970 dates stored as raw epoch numbers; unsigned values misparsed as signed; delta computations where minuend < subtrahend; garbage data in numeric columns.

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

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