apache/cassandra · error · MarshalException

Unable to coerce '%s' to a formatted date (long)

Error message

Unable to coerce '%s' to a formatted date (long)

What it means

dateStringToDays first tries to interpret the input as an ISO-8601 date string using DateTimeFormatter; if parsing throws DateTimeParseException or the epoch-milli arithmetic overflows (ArithmeticException), it wraps the failure in this MarshalException. It means the string is not a valid formatted date for the 'date' type.

Source

Thrown at src/java/org/apache/cassandra/serializers/SimpleDateSerializer.java:84

        }

        // Attempt to parse as date string
        try
        {
            LocalDate parsed = formatter.parse(source, LocalDate::from);
            long millis = parsed.atStartOfDay(UTC).toInstant().toEpochMilli();
            if (millis < minSupportedDateMillis)
                throw new MarshalException(String.format("Input date %s is less than min supported date %s", source,
                        ZonedDateTime.ofInstant(Instant.ofEpochMilli(minSupportedDateMillis), UTC).toString()));
            if (millis > maxSupportedDateMillis)
                throw new MarshalException(String.format("Input date %s is greater than max supported date %s", source,
                        ZonedDateTime.ofInstant(Instant.ofEpochMilli(maxSupportedDateMillis), UTC).toString()));

            return timeInMillisToDay(millis);
        }
        catch (DateTimeParseException| ArithmeticException e1)
        {
            throw new MarshalException(String.format("Unable to coerce '%s' to a formatted date (long)", source), e1);
        }
    }

    private static int parseRaw(String source) {
        try
        {
            long result = Long.parseLong(source);

            if (result < 0 || result > maxSupportedDays)
                throw new NumberFormatException("Input out of bounds: " + source);

            // Shift > epoch days into negative portion of Integer result for byte order comparability
            if (result >= Integer.MAX_VALUE)
                result -= byteOrderShift;

            return (int) result;
        }
        catch (NumberFormatException | DateTimeParseException e)

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Supply the date as ISO-8601 local date format: yyyy-MM-dd (optionally with a +/- sign and extended year for extreme dates)
  2. Quote the literal in CQL so it is parsed by the serializer rather than treated as an invalid token: '2011-02-03'
  3. If you already have the raw unsigned-int encoding, insert it as a quoted integer string (the serializer accepts it via parseRaw)
  4. Pre-validate with LocalDate.parse(input, DateTimeFormatter.ISO_LOCAL_DATE)

Example fix

// before
session.execute("INSERT INTO t (d) VALUES (?)", "02/03/2011");
// after
session.execute("INSERT INTO t (d) VALUES (?)", "2011-02-03");
Defensive patterns

Strategy: validation

Validate before calling

try { LocalDate.parse(input, DateTimeFormatter.ISO_LOCAL_DATE); } catch (DateTimeParseException e) { throw new IllegalArgumentException("expected yyyy-MM-dd: " + input); }

Type guard

static boolean isIsoDate(String s) {
  return s != null && ISO_LOCAL_DATE.matcher(s).matches(); // e.g. ^[+-]?\d{4,}-\d{2}-\d{2}$
}

Try / catch

try {
  session.execute(insert.bindString("d", input));
} catch (InvalidQueryException | MarshalException e) {
  if (e.getMessage().contains("formatted date")) throw new BadRequestException("use ISO yyyy-MM-dd for date columns");
  throw e;
}

Prevention

When it happens

Trigger: Passing a string that is not ISO_LOCAL_DATE format (e.g. '03/02/2011', 'Feb 3 2011', epoch millis '1345', empty string) to dateStringToDays or inserting such a literal into a date column without quoting/encoding.

Common situations: Locale-formatted dates pasted from UI code; sending a long (raw encoding or epoch millis) where an ISO string is expected; trailing whitespace or timezone suffixes like '2020-01-01T00:00:00Z'; old clients using pre-2.2 date formats.

Related errors

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