apache/cassandra · error · IllegalArgumentException

Snapshot name cannot contain

Error message

Snapshot name cannot contain 

What it means

validateTag rejects snapshot names containing the platform path separator, because the tag becomes a filesystem directory name and a separator would create unexpected nested paths (path traversal risk).

Source

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

        public SnapshotOptions build()
        {
            validateTag(tag);
            validateTTL(ephemeral, ttl);

            if (rateLimiter == null)
                rateLimiter = DatabaseDescriptor.getSnapshotRateLimiter();

            return new SnapshotOptions(this);
        }

        private void validateTag(String tag)
        {
            if (tag == null || tag.isEmpty())
                throw new IllegalArgumentException("You must supply a snapshot name.");

            if (tag.contains(File.pathSeparator()))
            {
                throw new IllegalArgumentException("Snapshot name cannot contain " + File.pathSeparator());
            }

            if (tag.equals(".") || tag.equals(".."))
            {
                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 -

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Replace separators in the tag with a safe character, e.g. tag.replace('/', '_').
2. Pre-validate the tag with a whitelist regex like [A-Za-z0-9._-]+ before calling the API.
3. Sanitize user-supplied snapshot names server-side before passing them to snapshot creation.
4. Use SnapshotOptions' validation (SNAPSHOT_NAME_VALIDATION property) in tests to catch bad tags early.

Example fix

// before
String tag = "daily/" + keyspace;
takeSnapshot(tag, keyspace);
// after
String tag = ("daily/" + keyspace).replace('/', '_');
takeSnapshot(tag, keyspace);

boolean isSafeTag(String tag) { return tag != null && tag.matches("[A-Za-z0-9._-]+") && !tag.equals(".") && !tag.equals(".."); }

try { takeSnapshot(tag, ks); } catch (IllegalArgumentException e) { log.error("Invalid snapshot tag '{}': {}", tag, e.getMessage()); }

When it happens

Trigger: Passing a tag containing '/' (or '\' on Windows), e.g. building hierarchical names like 'daily/ks1' or accepting user-controlled tags with slashes.

Common situations: Scripts composing tags from paths or URLs; multi-tenant input sanitization gaps; Windows/Linux tag reuse across environments.

Understand the failure class

Background: Path traversal blocked: "path escapes the workspace" and "outside site root" errors when a path will not stay inside its allowed directory — this error's family across 26 libraries.

Related errors

• You must supply a snapshot name.
• Snapshot name '' is reserved
• Snapshot name must not be more than %d characters long for r
• 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/92b2cef763fdf565. Report an issue: GitHub.