Edge Cases

Advanced scenarios and edge case handling for r2put.

Large Files

Behavior:

• No explicit size limits documented
• Depends on R2 service limits and available memory
• Very large files may take significant time to upload
• Monitor system resources (memory, disk space) during upload

Considerations:

• Progress bar shows simulated progress, not actual upload progress
• Network interruptions may cause upload to fail mid-transfer
• No automatic retry mechanism

Special Characters in Filenames

Behavior:

• Object key preserves special characters from filename
• Special characters in --file path require proper shell escaping
• Special characters in --key are preserved as-is

Examples:

# Filename with spaces
r2put --file "./my file.bin" --bucket my-bucket

# Filename with special characters (requires quoting)
r2put --file "./file (1).pdf" --bucket my-bucket

# Custom key with special characters
r2put --file ./data.bin --bucket my-bucket --key "path/to/file (backup).bin"

Best Practices:

• Use --key to specify clean object keys regardless of local filename
• Ensure object key is valid for R2 (follows S3 key rules)
• Quote paths with spaces or special characters

Empty Files

Behavior:

• Upload succeeds for empty files
• May have unexpected behavior in terminal UI
• Empty files are valid R2 objects

Example:

# Create empty file
touch empty.txt

# Upload empty file
r2put --file ./empty.txt --bucket my-bucket

Very Long Filenames

Behavior:

• Very long filenames may cause terminal UI layout issues
• Object keys can be long, but consider R2 key length limits
• Use --key to specify shorter object keys for long filenames

Example:

# Long filename
r2put --file "./very-long-filename-that-might-cause-ui-issues.bin" \
      --bucket my-bucket \
      --key "short-key.bin"

Non-Interactive Terminals

Behavior:

• Terminal UI may not render correctly in non-interactive environments
• Use with caution in CI/CD pipelines
• Exit codes still work correctly

Workarounds:

• Use @cfkit/r2 directly for programmatic control
• Redirect output if needed (UI may not render correctly)
• Check exit codes for success/failure

Concurrent Uploads

Behavior:

• Each invocation is independent
• No built-in coordination between concurrent uploads
• Multiple processes can upload simultaneously

Considerations:

• Ensure sufficient system resources for concurrent uploads
• Check R2 rate limits if many uploads fail
• Verify credentials have sufficient permissions
• Monitor network connectivity

Example:

# Upload multiple files concurrently (background processes)
r2put --file ./file1.bin --bucket my-bucket --key "files/file1.bin" &
r2put --file ./file2.bin --bucket my-bucket --key "files/file2.bin" &
r2put --file ./file3.bin --bucket my-bucket --key "files/file3.bin" &
wait  # Wait for all background jobs to complete

Network Interruptions

Behavior:

• Upload may fail mid-transfer
• No automatic retry mechanism
• Error message displayed, exit code 1

Handling:

• Implement retry logic in scripts if needed
• Check network connectivity before upload
• Monitor upload progress (though simulated in UI)

Example with Retry:

#!/bin/bash
MAX_RETRIES=3
RETRY_COUNT=0

while [ $RETRY_COUNT -lt $MAX_RETRIES ]; do
  r2put --file ./data.bin --bucket my-bucket
  
  if [ $? -eq 0 ]; then
    echo "Upload successful"
    exit 0
  fi
  
  RETRY_COUNT=$((RETRY_COUNT + 1))
  echo "Upload failed, retry $RETRY_COUNT/$MAX_RETRIES"
  sleep 5
done

echo "Upload failed after $MAX_RETRIES attempts"
exit 1

Invalid Bucket Names

Behavior:

• R2 validates bucket names
• Tool passes through R2 error messages
• Exit code 1 on validation failure

Common Issues:

• Bucket name doesn't exist
• Bucket name format invalid
• Insufficient permissions to access bucket

Invalid Object Keys

Behavior:

• R2 validates object keys
• Tool passes through R2 error messages
• Exit code 1 on validation failure

Key Rules:

• Must follow S3 key rules
• Cannot exceed maximum length
• Special characters may need encoding

Missing File Permissions

Behavior:

• Tool cannot read file if permissions insufficient
• Displays file system error
• Exit code 1

Resolution:

• Check file permissions: ls -l <file>
• Ensure file is readable: chmod +r <file>
• Verify file ownership if needed

Disk Space

Behavior:

• No explicit disk space check before upload
• Upload may fail if insufficient space for temporary operations
• Error message may not explicitly mention disk space

Monitoring:

• Check available disk space before large uploads
• Monitor disk usage during upload
• Clean up temporary files if needed

MIME Type Detection Edge Cases

Behavior:

• Falls back to application/octet-stream for unknown extensions
• Case-insensitive extension matching
• Uses last extension if multiple extensions (e.g., file.tar.gz → application/gzip)
• No content-based detection (extension-only)

Examples:

# Multiple extensions - uses last one
r2put --file ./archive.tar.gz --bucket my-bucket
# Detects as application/gzip (from .gz)

# Unknown extension
r2put --file ./data.unknown --bucket my-bucket
# Detects as application/octet-stream

# Case variations
r2put --file ./image.JPG --bucket my-bucket
# Detects as image/jpeg (case-insensitive)

Workaround:

• Use @cfkit/r2 directly to set specific MIME type
• Rename file with recognized extension if needed

Presigned URL Generation Failures

Behavior:

• May fail if R2 service has issues
• Tool displays error message
• Upload may have succeeded even if URL generation fails
• Exit code 1

Handling:

• Check R2 service status
• Verify object was uploaded (check R2 dashboard or API)
• Retry URL generation if needed (requires new upload or using R2 API directly)

Relative vs Absolute Paths

Behavior:

• Both relative and absolute paths supported
• Relative paths resolved from current working directory
• Absolute paths used as-is
• Shell expansion applies (e.g., ~ for home directory)

Examples:

# Relative path
cd /home/user
r2put --file ./data.bin --bucket my-bucket

# Absolute path
r2put --file /home/user/data.bin --bucket my-bucket

# Shell expansion
r2put --file ~/Documents/file.pdf --bucket my-bucket

Best Practices:

• Use absolute paths in scripts for reliability
• Use relative paths for convenience in interactive use
• Be aware of current working directory in scripts