[Bug]: create_snapshot/drop_snapshot accepts whitespace-only snapshot_name - missing validation

[zhuwenxing]

Is there an existing issue for this?

• I have searched the existing issues

Environment

• Milvus version: master-20260114-eb63a363-amd64
• Deployment mode: standalone
• SDK version: pymilvus 2.7.0rc113
• OS: macOS / Linux

Current Behavior

create_snapshot and drop_snapshot APIs accept whitespace-only strings (e.g., " ", " ") as snapshot_name without validation. This creates snapshots with invalid names that are difficult to manage.

# This should fail but succeeds
client.create_snapshot(collection_name="test_col", snapshot_name=" ")  # Single space - OK??
client.create_snapshot(collection_name="test_col", snapshot_name="  ")  # Two spaces - OK??

Expected Behavior

The server should reject whitespace-only snapshot_name with a clear error message:

ParamError: snapshot_name must be a non-empty string (after trimming whitespace)

Steps To Reproduce

from pymilvus import MilvusClient

client = MilvusClient('http://localhost:19530')

# Create collection
client.create_collection("test_col", dimension=128)

# Create snapshot with whitespace-only name - should fail but succeeds
client.create_snapshot(collection_name="test_col", snapshot_name=" ")
print("Created snapshot with name=' ' (single space)")

# List snapshots - the whitespace snapshot appears
snapshots = client.list_snapshots(collection_name="test_col")
print(f"Snapshots: {snapshots}")  # Contains ' '

# Try to create another one with same whitespace name
try:
    client.create_snapshot(collection_name="test_col", snapshot_name=" ")
except Exception as e:
    print(f"Second creation fails: {e}")  
    # Error message is confusing: "snapshot name  already exists"

Root Cause Analysis

Server Side

The server-side validation in internal/proxy/task_snapshot.go doesn't check for whitespace-only names:

CreateSnapshot (lines 97-105):

func (cst *createSnapshotTask) PreExecute(ctx context.Context) error {
    // Only validates collection exists, no snapshot_name validation
    collectionID, err := globalMetaCache.GetCollectionID(ctx, cst.req.GetDbName(), cst.req.GetCollectionName())
    if err != nil {
        return err
    }
    cst.collectionID = collectionID
    return nil  // No validation for empty/whitespace snapshot_name
}

DropSnapshot (lines 183-186):

func (dst *dropSnapshotTask) PreExecute(ctx context.Context) error {
    // No additional validation needed for drop snapshot
    return nil  // Comment explicitly says no validation!
}

SDK Side (pymilvus)

The SDK's validate_str() function in pymilvus/client/check.py only checks for empty strings, not whitespace:

def validate_str(var: Any) -> bool:
    """check if a variable is legal non-empty str"""
    return var and isinstance(var, str)  # " " is truthy, so it passes

Suggested Fix

Server Side (Preferred)

Add validation in createSnapshotTask.PreExecute and dropSnapshotTask.PreExecute:

import "strings"

func (cst *createSnapshotTask) PreExecute(ctx context.Context) error {
    // Add snapshot_name validation
    if strings.TrimSpace(cst.req.GetName()) == "" {
        return merr.WrapErrParameterInvalidMsg("snapshot_name must be a non-empty string")
    }
    
    collectionID, err := globalMetaCache.GetCollectionID(ctx, cst.req.GetDbName(), cst.req.GetCollectionName())
    if err != nil {
        return err
    }
    cst.collectionID = collectionID
    return nil
}

func (dst *dropSnapshotTask) PreExecute(ctx context.Context) error {
    if strings.TrimSpace(dst.req.GetName()) == "" {
        return merr.WrapErrParameterInvalidMsg("snapshot_name must be a non-empty string")
    }
    return nil
}

SDK Side (Additional)

Update validate_str() to strip whitespace:

def validate_str(var: Any) -> bool:
    """check if a variable is legal non-empty str"""
    return var and isinstance(var, str) and var.strip()

Impact

• Creates "invisible" snapshots that are hard to identify and manage
• Confusing error messages when trying to create duplicate whitespace snapshots
• Potential for orphaned snapshots that can't be easily cleaned up
• Poor user experience and API hygiene

Milvus Log

N/A

Anything else?

This was discovered during Snapshot feature testing. Related test cases:

• test_snapshot_create_whitespace_name
• test_snapshot_drop_whitespace_name

Note: Empty string "" and None are correctly rejected by pymilvus SDK (PR #3083), but whitespace-only strings pass through both SDK and server validation.

Related to: #44358 (Snapshot feature)

[zhuwenxing]

Additional Suggestion: Use same validation rules as collection_name

After further analysis, I suggest snapshot_name should follow the same validation rules as collection_name, not just check for empty/whitespace.

Current collection_name validation (internal/proxy/util.go:213-235)

func validateCollectionNameOrAlias(entity, entityType string) error {
    // 1. Cannot be empty
    if entity == "" {
        return merr.WrapErrParameterInvalidMsg("collection %s should not be empty", entityType)
    }
    
    // 2. Length limit (default 255)
    if len(entity) > Params.ProxyCfg.MaxNameLength.GetAsInt() {
        return merr.WrapErrParameterInvalidMsg("...")
    }
    
    // 3. First character must be underscore or letter
    firstChar := entity[0]
    if firstChar != '_' && !isAlpha(firstChar) {
        return merr.WrapErrParameterInvalidMsg("...")
    }
    
    // 4. Only alphanumeric and underscore allowed
    for i := 1; i < len(entity); i++ {
        c := entity[i]
        if c != '_' && !isAlpha(c) && !isNumber(c) {
            return merr.WrapErrParameterInvalidMsg("...")
        }
    }
    return nil
}

Invalid names (from unit tests):

• "" - empty string
• " " - whitespace
• "123abc" - starts with number
• "$abc" - special characters
• "_12 ac" - contains space
• "中文" - non-ASCII characters
• "abc " - trailing space

Suggested implementation

Add a validateSnapshotName function that reuses the existing logic:

func validateSnapshotName(name string) error {
    return validateCollectionNameOrAlias(name, "snapshot name")
}

Then call it in createSnapshotTask.PreExecute and dropSnapshotTask.PreExecute:

func (cst *createSnapshotTask) PreExecute(ctx context.Context) error {
    if err := validateSnapshotName(cst.req.GetName()); err != nil {
        return err
    }
    // ... rest of the code
}

Benefits

• Consistent naming rules across all Milvus entities (collection, partition, index, snapshot)
• Users learn one set of naming conventions
• Prevents edge cases like spaces, special characters, non-ASCII names
• Reuses well-tested validation code

[zhuwenxing]

/assign @weiliu1031