apache/cassandra · error · IllegalArgumentException

Parameter --older-than-timestamp has to be a valid instant…

Error message

Parameter --older-than-timestamp has to be a valid instant in ISO format.

What it means

IllegalArgumentException from ClearSnapshot.execute: the --older-than-timestamp value failed to parse as a valid ISO-8601 instant. The flag requires an absolute timestamp (e.g. 2024-01-01T00:00:00Z); any other format is rejected before snapshots are cleared.

Solutions

Format the value as ISO-8601 instant, e.g. `--older-than-timestamp 2026-01-01T00:00:00Z`
Generate it in shell with `date -u +%Y-%m-%dT%H:%M:%SZ`
Use `--older-than <duration>` (e.g. 7d) instead if an absolute timestamp is awkward

Example fix

// before
nodetool clearsnapshot --all --older-than-timestamp 2026-01-01
// after
nodetool clearsnapshot --all --older-than-timestamp 2026-01-01T00:00:00Z

Defensive patterns

Strategy: validation

Validate before calling

from datetime import datetime, timezone
ts = datetime.now(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ')
# pass e.g. 2026-01-01T00:00:00Z; validate:
datetime.strptime(ts, '%Y-%m-%dT%H:%M:%SZ')

Try / catch

try { clearSnapshot(); }
catch (IllegalArgumentException e) { System.err.println("use ISO-8601 instant, e.g. 2026-01-01T00:00:00Z"); }

Prevention

Always include time and Z timezone designator
Generate timestamps with date -u +%Y-%m-%dT%H:%M:%SZ
Prefer --older-than durations for relative cutoffs

When it happens

Trigger: Passing dates like `2026-01-01`, `01/01/2026`, epoch seconds `1767225600`, or timestamps missing the UTC 'Z' designator to --older-than-timestamp.

Common situations: Shell date output in non-ISO formats, users giving plain dates without time/timezone, epoch milliseconds pasted instead of ISO strings.

Related errors

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

Appendix: source

Thrown at src/java/org/apache/cassandra/tools/nodetool/ClearSnapshot.java:85

            throw new IllegalArgumentException("Specify only one of snapshot name or --all");

        if (olderThan != null && olderThanTimestamp != null)
            throw new IllegalArgumentException("Specify only one of --older-than or --older-than-timestamp");

        if (!snapshotName.isEmpty() && olderThan != null)
            throw new IllegalArgumentException("Specifying snapshot name together with --older-than flag is not allowed");

        if (!snapshotName.isEmpty() && olderThanTimestamp != null)
            throw new IllegalArgumentException("Specifying snapshot name together with --older-than-timestamp flag is not allowed");

        if (olderThanTimestamp != null)
            try
            {
                Instant.parse(olderThanTimestamp);
            }
            catch (DateTimeParseException ex)
            {
                throw new IllegalArgumentException("Parameter --older-than-timestamp has to be a valid instant in ISO format.");
            }

        Long olderThanInSeconds = null;
        if (olderThan != null)
            // fail fast when it is not valid
            olderThanInSeconds = new DurationSpec.LongSecondsBound(olderThan).toSeconds();

        StringBuilder sb = new StringBuilder();

        sb.append("Requested clearing snapshot(s) for ");

        if (keyspaces.isEmpty())
            sb.append("[all keyspaces]");
        else
            sb.append('[').append(join(keyspaces, ", ")).append(']');

        if (snapshotName.isEmpty())
            sb.append(" with [all snapshots]");

View on GitHub (pinned to 88fd0f6a0e)