What causes "Invalid null value of timestamp" in apache/cassandra?

Bind a concrete long (e.g. System.currentTimeMillis() * 1000) or use Unset/omit the USING TIMESTAMP clause when the timestamp should be defaulted

apache/cassandra · error · InvalidRequestException

Invalid null value of timestamp

Error message

Invalid null value of timestamp

What it means

Attributes.getTimestamp resolves the USING TIMESTAMP term of an INSERT/UPDATE; if the bound term evaluates to null (the protocol sent null for the timestamp bind marker), the write has no well-defined timestamp, so Cassandra throws InvalidRequestException. Note an unset (UNSET_BYTE_BUFFER) value is allowed and falls back to 'now'.

Source

Thrown at src/java/org/apache/cassandra/cql3/Attributes.java:92

    public boolean isTimestampSet()
    {
        return timestamp != null;
    }

    public boolean isTimeToLiveSet()
    {
        return timeToLive != null;
    }

    public long getTimestamp(long now, FunctionContext context) throws InvalidRequestException
    {
        if (timestamp == null)
            return now;

        ByteBuffer tval = timestamp.bindAndGet(context);
        if (tval == null)
            throw new InvalidRequestException("Invalid null value of timestamp");

        if (tval == ByteBufferUtil.UNSET_BYTE_BUFFER)
            return now;

        try
        {
            LongType.instance.validate(tval);
        }
        catch (MarshalException e)
        {
            throw new InvalidRequestException("Invalid timestamp value: " + tval);
        }

        return LongType.instance.compose(tval);
    }

    public int getTimeToLive(FunctionContext context, TableMetadata metadata) throws InvalidRequestException
    {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Bind a concrete long (e.g. System.currentTimeMillis() * 1000) or use Unset/omit the USING TIMESTAMP clause when the timestamp should be defaulted
Use unset values (Unset.valueOf / unset bound variables) instead of null so the server falls back to 'now'
Guard client-side: check the timestamp parameter for null before executing the statement
If using JSON inserts, drop the [timestamp] column/field rather than sending null

Example fix

// before
BoundStatement bs = ps.bind().setLong(0, id).setLong(1, null); // USING TIMESTAMP ?
// after
BoundStatement bs = ps.bind().setLong(0, id);
bs.set(1, System.currentTimeMillis() * 1000L, Long.class); // or omit USING TIMESTAMP

Defensive patterns

Strategy: try-catch

Validate before calling

if (timestamp == null)
    throw new IllegalArgumentException("USING TIMESTAMP value must not be null; use unset or a concrete long");

Type guard

boolean isValidTimestamp(Long ts) { return ts != null && ts >= 0; }

Try / catch

try {
    session.execute(bs);
} catch (com.datastax.oss.driver.api.core.servererrors.InvalidQueryException e) {
    if (e.getMessage().contains("Invalid null value of timestamp"))
        log.error("Bind a real timestamp or unset the USING TIMESTAMP term");
    throw e;
}

Prevention

Never bind null into USING TIMESTAMP markers
Use driver unset values for optional USING clauses
Add client-side null checks for write-metadata parameters
For JSON inserts, omit the timestamp field instead of sending null

When it happens

Trigger: Executing INSERT/UPDATE with 'USING TIMESTAMP ?' and supplying null as the bound value of the timestamp parameter (or a JSON bind producing null); timestamp bind marker used but client sends null.

Common situations: Driver code passing a null Integer/Long into a bound statement for the timestamp; JSON-based inserts where the timestamp field is null; ORMs serializing missing optional fields as null.

Related errors

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