apache/cassandra · error · IllegalArgumentException

Snapshot name must not be more than %d characters long for r

Error message

Snapshot name must not be more than %d characters long for resolved snapshot name (got %d characters for "%s")

What it means

When snapshot-name validation is enabled, the fully resolved snapshot name (built from snapshot type, tag, and timestamp) must fit the filesystem's FILENAME_LENGTH limit (255 chars, mirroring table-name limits). Over-long resolved names are rejected with the computed and actual lengths in the message.

Source

Thrown at src/java/org/apache/cassandra/service/snapshot/SnapshotOptions.java:242

            {
                throw new IllegalArgumentException("Snapshot name '" + tag + "' is reserved");
            }

            if (!CassandraRelevantProperties.SNAPSHOT_NAME_VALIDATION.getBoolean())
                return;

            // Pre-generate snapshot name for the sake of the validation.
            // getSnapshotName logic does not return raw "tag" as snapshot name every time,
            // it e.g. prepends timestamp and type for system snapshots, and we need to validate it as a whole.
            // If, for example, tag would be less than max allowed FILENAME_LENGTH,
            // we might in fact produce a snapshot name longer than FILENAME_LENGTH if we prepended a timestamp to it.
            String resolvedSnapshotName = SnapshotOptions.getSnapshotName(type, tag, now());

            // the length of valid snapshot name has to be less than or equal to FILENAME_LEGTH - that is 255 -
            // we are following the max length as it is in SchemaConstants for table name.
            if (resolvedSnapshotName.length() > SchemaConstants.FILENAME_LENGTH)
            {
                throw new IllegalArgumentException(format("Snapshot name must not be more than %d characters long for " +
                                                          "resolved snapshot name (got %d characters for \"%s\")",
                                                          FILENAME_LENGTH, resolvedSnapshotName.length(), resolvedSnapshotName));
            }

            // Allowed characters are a conservative subset of the AWS S3 "Safe characters" set
            // (https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-keys.html#object-key-guidelines):
            //   0-9  a-z  A-Z  -  _  .
            // plus '+', which is not an S3 "Safe character" but can legitimately appear in system
            // snapshot names via version build metadata (e.g. an upgrade snapshot "<millis>-upgrade-5.0.4+build-...").
            // The remaining S3-safe characters (! * ' ( )) are intentionally excluded as they are
            // shell-significant and error-prone in paths, and the path separator '/' is excluded too,
            // which is what blocks traversal attempts such as "../../mysnapshot"
            if (!SAFE_SNAPSHOT_NAME.matcher(resolvedSnapshotName).matches())
            {
                throw new IllegalArgumentException("Snapshot name contains illegal characters: " + resolvedSnapshotName + ". " +
                                                   "Allowed characters must match the pattern: " + SAFE_SNAPSHOT_NAME.pattern() +
                                                   " with a maximum of length of " + FILENAME_LENGTH + " characters.");
            }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Shorten the snapshot tag so the resolved name fits within 255 characters.
2. Hash or truncate long identifiers before embedding them in the tag (e.g. SHA-256 prefix of the label).
3. Check length before calling: SnapshotOptions.getSnapshotName(type, tag, Instant.now()).length() <= SchemaConstants.FILENAME_LENGTH.
4. Keep tags short and put auxiliary metadata outside the snapshot name.

Example fix

// before
String tag = "backup-" + allTableNames; // >255 chars resolved
// after
String tag = "backup-" + DigestUtils.sha256Hex(allTableNames).substring(0, 12);

boolean fitsFilename(String type, String tag, Instant now) { return SnapshotOptions.getSnapshotName(type, tag, now).length() <= SchemaConstants.FILENAME_LENGTH; }

try { options.build(); } catch (IllegalArgumentException e) { if (e.getMessage().contains("characters long")) { log.error("Shorten snapshot tag"); } throw e; }

When it happens

Trigger: Supplying an excessively long tag such that type + tag + timestamp exceeds 255 characters in the resolved name; long keyspace/table-derived names combined with a long user tag.

Common situations: Generated tags embedding long hostnames, table lists, or ISO timestamps repeatedly; automated backup frameworks concatenating many labels into the tag.

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

• You must supply a snapshot name.
• Snapshot name cannot contain
• Snapshot name '' is reserved
• Invalid throttle for snapshot_links_per_second: must be posi
• Snapshot name contains illegal characters: . Allowed charact

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