apache/cassandra · error · RuntimeException

Parameter older_than_timestamp has to be a valid instant in…

Error message

Parameter older_than_timestamp has to be a valid instant in ISO format.

What it means

Thrown by getPredicateForCleanedSnapshots when the older_than_timestamp parameter cannot be parsed as an ISO-8601 instant via Instant.parse. The snapshot-clear API expects an absolute timestamp; any malformed or non-ISO string fails before a snapshot deletion predicate is built.

Solutions

1. Convert the value to a full ISO-8601 instant with trailing 'Z', e.g. date -u -d @1700000000 +%Y-%m-%dT%H:%M:%SZ.
2. Validate the string with java.time.Instant.parse (or DateTimeFormatter.ISO_INSTANT) before invoking the API.
3. If only a relative age is intended, omit older_than_timestamp and use the snapshot-age based clearing options instead.
4. Catch DateTimeParseException around Instant.parse in wrapper scripts and report the exact expected format.

Example fix

// before
clearSnapshot("ks1", "tag1", "1700000000");
// after
clearSnapshot("ks1", "tag1", Instant.ofEpochSecond(1700000000).toString()); // 2023-11-14T22:13:20Z

boolean isValidInstant(String s) { try { Instant.parse(s); return true; } catch (DateTimeParseException | NullPointerException e) { return false; } }

try { mgr.clearSnapshotsWithTimestamp(isoInstant); } catch (RuntimeException e) { log.error("older_than_timestamp must be ISO-8601 instant, e.g. 2024-01-01T00:00:00Z", e); }

When it happens

Trigger: Calling clear-snapshot (nodetool/JMX) with older_than_timestamp set to a value that Instant.parse rejects, e.g. 'yesterday', '2024-01-01' (date only, no time/zone), '1700000000' (epoch seconds), or empty string.

Common situations: Operators pass unix epoch seconds or human dates ('2024-01-01', 'now-7d') instead of the required ISO instant like '2024-01-01T00:00:00Z'; scripts build timestamps with the wrong date formatter.

Related errors

• Error during taking a snapshot
• Snapshot name cannot contain
• When specifying the Keyspace table list (using…
• argument for sort must be one of
• argument for top must be a positive integer.

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

Appendix: source

Thrown at src/java/org/apache/cassandra/service/snapshot/ClearSnapshotTask.java:124

        Object olderThan = options.get("older_than");
        Object olderThanTimestamp = options.get("older_than_timestamp");

        long maxCreatedAt = Clock.Global.currentTimeMillis();
        if (olderThan != null)
        {
            assert olderThan instanceof String : "it is expected that older_than is an instance of java.lang.String";
            maxCreatedAt -= new DurationSpec.LongSecondsBound((String) olderThan).toMilliseconds();
        }
        else if (olderThanTimestamp != null)
        {
            assert olderThanTimestamp instanceof String : "it is expected that older_than_timestamp is an instance of java.lang.String";
            try
            {
                maxCreatedAt = Instant.parse((String) olderThanTimestamp).toEpochMilli();
            }
            catch (DateTimeParseException ex)
            {
                throw new RuntimeException("Parameter older_than_timestamp has to be a valid instant in ISO format.");
            }
        }

        return getClearSnapshotPredicate(tag, Set.of(keyspaceNames), maxCreatedAt, false);
    }

    /**
     * Returns a predicate based on which a snapshot will be included for deletion or not.
     *
     * @param tag                name of snapshot to remove
     * @param keyspaces          keyspaces this snapshot belongs to
     * @param olderThanTimestamp clear the snapshot if it is older than given timestamp
     * @param includeEphemeral   whether to include ephemeral snapshots as well
     * @return predicate which filters snapshots on given parameters
     */
    static Predicate<TableSnapshot> getClearSnapshotPredicate(String tag,
                                                              Set<String> keyspaces,
                                                              long olderThanTimestamp,

View on GitHub (pinned to 88fd0f6a0e)