apache/cassandra · error · IllegalArgumentException

You must supply a snapshot name.

Error message

You must supply a snapshot name.

What it means

SnapshotOptions.Builder.validateTag rejects null or empty snapshot tags with an IllegalArgumentException before building options. A snapshot name is mandatory because it becomes the snapshot directory name.

Source

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

            this.rateLimiter = rateLimiter;
            return this;
        }

        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,

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Supply a non-empty snapshot name to the builder/command (e.g. -t mytag for nodetool snapshot).
2. Default missing tags in your script, e.g. "backup-$(date +%s)".
3. Validate tag presence before invoking the snapshot API and fail fast with a clear message.
4. Check config/templating so empty values do not silently drop the tag argument.

Example fix

// before
String tag = System.getProperty("snapshot.tag"); // may be null
builder.withTag(tag).build();
// after
String tag = System.getProperty("snapshot.tag", "backup-" + System.currentTimeMillis());
if (tag == null || tag.isEmpty()) throw new IllegalArgumentException("snapshot.tag is required");
builder.withTag(tag).build();

String requireTag(String tag) { if (tag == null || tag.isEmpty()) throw new IllegalArgumentException("snapshot tag is required"); return tag; }

try { builder.withTag(tag).build(); } catch (IllegalArgumentException e) { log.error("Snapshot tag missing: {}", e.getMessage()); }

When it happens

Trigger: Building SnapshotOptions (or calling takeSnapshot paths) without supplying a tag; passing an empty string tag from a config-driven or scripted invocation.

Common situations: Automation where the tag variable is unset or substituted to empty; API/JMX callers omitting the snapshot name parameter.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Snapshot name cannot contain
• 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/b305ac0de3fa200d. Report an issue: GitHub.