Error Handling Reference

Complete error handling documentation for r2put.

Error Behavior

All errors result in:

• Exit code 1
• Error message displayed in terminal UI
• Help message suggested for argument errors
• R2 client errors passed through and displayed

Error Categories

Missing Required Arguments

Error Message:

ERROR: Missing required argument: --file

Run with --help for usage information.

Causes:

• --file argument not provided
• --bucket argument not provided

Resolution:

• Provide all required arguments
• Check command syntax
• Run with --help for usage information

File Not Found

Error Message:

ERROR: File not found: /path/to/nonexistent.bin

Run with --help for usage information.

Causes:

• File path is incorrect
• File doesn't exist
• Typo in file path

Resolution:

• Verify file path is correct
• Use absolute path if unsure
• Check for typos in file path
• Ensure file exists before running command

Not a File (Directory)

Error Message:

ERROR: Not a file: /path/to/directory

Run with --help for usage information.

Causes:

• Path points to a directory instead of a file
• Incorrect path specified

Resolution:

• Specify a file path, not a directory
• Check path points to an actual file
• Use file path, not directory path

Missing Environment Variables

Error Message:

ERROR: Missing CLOUDFLARE_ACCOUNT_ID environment variable

Run with --help for usage information.

Causes:

• Required environment variable not set
• Variable name misspelled
• Variable not exported

Resolution:

• Set all three required environment variables:
  • CLOUDFLARE_ACCOUNT_ID
  • R2_ACCESS_KEY_ID
  • R2_SECRET_ACCESS_KEY
• Verify variable names are correct
• Ensure variables are exported (use export)
• Check variables are set before invocation

Upload Errors

Error Display:

• Displayed in red border box in terminal UI
• Error message from R2 client
• May include specific R2 error codes

Common Causes:

• Invalid bucket name
• Bucket doesn't exist
• Insufficient permissions
• Invalid object key
• Network connectivity issues
• R2 service issues

Resolution:

• Verify bucket name is correct
• Check bucket exists and is accessible
• Ensure credentials have write permissions
• Verify object key is valid (follows S3 key rules)
• Check network connectivity
• Review R2 service status

Network Errors

Error Display:

• Connection error message
• Network-related error details

Causes:

• Network connectivity issues
• Firewall blocking connection
• DNS resolution problems
• R2 service unavailable

Resolution:

• Check network connectivity
• Verify firewall settings
• Check DNS resolution
• Review R2 service status
• Retry upload after network issues resolved

Authentication Errors

Error Display:

• Credential error from R2 client
• Authentication failure message

Causes:

• Incorrect credentials
• Expired credentials
• Invalid account ID
• Credentials don't match account

Resolution:

• Verify all three environment variables are correct
• Check credentials are not expired
• Ensure account ID matches the account containing the bucket
• Verify credentials have permissions to write to the specified bucket
• Regenerate credentials if needed

Error Handling Behavior

Exit Codes

• 0 - Upload completed successfully
• 1 - Any error occurred

Error Message Display

• All errors exit with code 1
• Error messages displayed in terminal UI
• Help message suggested for argument errors
• R2 client errors passed through and displayed
• Network errors caught and displayed
• Authentication errors caught and displayed

Troubleshooting Common Errors

Upload Fails with Authentication Error

Symptoms:

• Authentication error message
• Exit code 1

Resolution:

• Verify all three environment variables are set: CLOUDFLARE_ACCOUNT_ID, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY
• Check that credentials are correct and not expired
• Ensure credentials have permissions to write to the specified bucket
• Verify account ID matches the account containing the bucket

File Not Found Error

Symptoms:

• "File not found" error message
• Exit code 1

Resolution:

• Verify file path is correct (use absolute path if unsure)
• Check file permissions (must be readable)
• Ensure file exists before running command
• Check for typos in file path

Upload Hangs or Times Out

Symptoms:

• Upload process hangs
• No progress or error message

Resolution:

• Check network connectivity to Cloudflare R2
• Verify bucket name is correct
• Check R2 service status
• Review file size (very large files may take time)
• Check system resources (memory, disk space)

Exit Code Always 1

Symptoms:

• Command always exits with code 1
• May or may not show error message

Resolution:

• Check error message in terminal output
• Verify all required arguments are provided
• Ensure environment variables are set
• Check file exists and is readable
• Verify bucket name is correct
• Review R2 service status

Multiple Uploads Fail

Symptoms:

• Multiple upload attempts fail
• May be rate limiting or resource issues

Resolution:

• Each upload is independent; no built-in coordination
• Ensure sufficient resources for concurrent uploads
• Check R2 rate limits if many uploads fail
• Verify credentials have sufficient permissions
• Review network connectivity

Error Prevention

Pre-flight Checks

Before running r2put, verify:

1. File exists and is readable:

   test -f ./data.bin && echo "File exists"

2. Environment variables are set:

   [ -n "$CLOUDFLARE_ACCOUNT_ID" ] && [ -n "$R2_ACCESS_KEY_ID" ] && [ -n "$R2_SECRET_ACCESS_KEY" ] && echo "All variables set"

3. Bucket name is correct:

   • Verify in Cloudflare dashboard
   • Check bucket exists and is accessible

4. Network connectivity:

   • Test connection to R2 service
   • Check firewall settings

Script Error Handling

Example script with error handling:

#!/bin/bash
set -e

# Verify file exists
if [ ! -f "./data.bin" ]; then
  echo "Error: File not found"
  exit 1
fi

# Verify environment variables
if [ -z "$CLOUDFLARE_ACCOUNT_ID" ] || [ -z "$R2_ACCESS_KEY_ID" ] || [ -z "$R2_SECRET_ACCESS_KEY" ]; then
  echo "Error: Missing required environment variables"
  exit 1
fi

# Attempt upload
r2put --file ./data.bin --bucket my-bucket

# Check result
if [ $? -eq 0 ]; then
  echo "Upload successful"
else
  echo "Upload failed"
  exit 1
fi