1

S3 RenameObject

Chris Lu edited this page 2026-08-09 22:33:39 -07:00

Table of Contents

• S3 RenameObject
• How It Works
• Request
• Conditional Headers
• Restrictions
• Errors

S3 RenameObject

SeaweedFS supports the S3 RenameObject API: rename an object within a bucket in one atomic, metadata-only operation. AWS offers this API only on directory buckets (S3 Express One Zone); SeaweedFS provides it on regular buckets.

Available since version 4.42.

How It Works

The rename is executed by the filer as an atomic metadata move. The object's data is never read or rewritten, so renaming a 1 TB object costs the same as renaming a 1 KB one, and the ETag, tags, user metadata, and encryption metadata all travel unchanged.

Both keys are write-locked for the duration of the operation, and all precondition headers are evaluated under those locks, so a conditional rename is atomic cluster-wide — the same guarantee as S3 Conditional Operations.

Request

PUT /{bucket}/{destination-key}?renameObject
x-amz-rename-source: {source-key}

The x-amz-rename-source value can be a bare key (old-name.txt) or bucket-qualified (mybucket/old-name.txt), with or without a leading slash — AWS's own examples use both forms. The value is read as a literal key first; only when no such object exists and the value starts with the request's own bucket name is it re-read as bucket/key. Cross-bucket renames are not supported: the source bucket is always the request's bucket.

With the AWS CLI:

aws --endpoint-url http://localhost:8333 s3api rename-object \
  --bucket mybucket \
  --key new-name.txt \
  --rename-source mybucket/old-name.txt

Or as a raw request:

curl -X PUT -H "x-amz-rename-source: old-name.txt" \
  "http://localhost:8333/mybucket/new-name.txt?renameObject"

Conditional Headers

Like CopyObject, a rename can carry conditions for both ends of the operation independently.

The source is conditioned with rename-source headers:

Header	Type
x-amz-rename-source-if-match	ETag
x-amz-rename-source-if-none-match	ETag
x-amz-rename-source-if-modified-since	RFC 1123 date
x-amz-rename-source-if-unmodified-since	RFC 1123 date

The destination is conditioned with the four standard headers (If-Match, If-None-Match, If-Modified-Since, If-Unmodified-Since). The most useful one: an existing destination object is silently replaced, as with PutObject, so send If-None-Match: * to make the rename fail with PreconditionFailed instead of overwriting.

curl -X PUT \
  -H "x-amz-rename-source: old-name.txt" \
  -H "If-None-Match: *" \
  "http://localhost:8333/mybucket/new-name.txt?renameObject"

Restrictions

• Unversioned buckets only. A bucket with versioning enabled or suspended — including any bucket with Object Lock, which implies versioning — returns 501 NotImplemented. This matches AWS, where RenameObject exists only on directory buckets, which cannot be versioned.
• Objects only. A key with a trailing slash names a directory, and renaming one would move a whole subtree; both ends reject it. An object whose key is also a prefix of other keys (a "directory object") cannot be renamed either.
• Source read + delete permission. The caller needs write permission on the destination (it is the request URL), plus read and delete permission on the source, since the rename both reads the object and removes its old key.
• No idempotency replay. x-amz-client-token is accepted — AWS SDKs fill it in automatically — but retrying a rename that already succeeded returns NoSuchKey, because the source is gone.

Errors

Condition	Error
Source object does not exist	NoSuchKey (404)
Bucket is versioned	NotImplemented (501)
Destination same as source	InvalidRequest (400)
Missing or empty x-amz-rename-source	InvalidArgument (400)
A directory exists at the destination key	ExistingObjectIsDirectory (409)
A precondition failed	PreconditionFailed (412)

Introduction

• Quick Start with weed mini
• Simplest S3 Bucket and User Setup
• Components
• Blob Store Architecture
• Getting Started
• Production Setup
• A typical step‐by‐step example
• Benchmarks
• FAQ
• Applications

API

• Master Server API
• Volume Server API
• Filer Server API
• Client Libraries
• SeaweedFS Java Client

Configuration

• Replication
• Store file with a Time To Live
• Failover Master Server
• Erasure coding for warm storage
• EC Bitrot Detection
• Server Startup via Systemd
• Environment Variables

Filer

• Filer Setup
• Directories and Files
• File Operations Quick Reference
• Data Structure for Large Files
• Filer Data Encryption
• Filer Commands and Operations
• Filer JWT Use
• TUS Resumable Uploads

Filer Stores

• Filer Cassandra Setup
• Filer Redis Setup
• Super Large Directories
• Path-Specific Filer Store
• Choosing a Filer Store
• Customize Filer Store

Management

• Admin UI
• Admin UI OIDC
• Worker
• Plugin Worker Scheduling

Advanced Filer Configurations

• Migrate to Filer Store
• Add New Filer Store
• Filer Store Replication
• Filer Active Active cross cluster continuous synchronization
• Filer as a Key-Large-Value Store
• Path Specific Configuration
• Filer Change Data Capture
• Filer Operation Serialization

FUSE Mount

• Mount on Windows
• FIO benchmark
• fstab and systemd mount
• POSIX Compliance
• Distributed POSIX Locks
• P2P reading in weed mount
• Mount over the Internet

WebDAV

SFTP Server

Cloud Drive

• Cloud Drive Benefits
• Cloud Drive Architecture
• Configure Remote Storage
• Azure Blob Storage Authentication
• Mount Remote Storage
• Cache Remote Storage
• Cloud Drive Quick Setup
• Gateway to Remote Object Storage

AWS S3 API

• Amazon S3 API
• Supported APIs vs Minio
• S3 Lifecycle
  • S3 Lifecycle Recipes
  • S3 Lifecycle Operator Guide
  • S3 Lifecycle Monitoring
  • S3 Lifecycle Troubleshooting
  • S3 Lifecycle Architecture
• S3 Lifecycle vs Volume TTL
• S3 Conditional Operations
• S3 CORS
• S3 Object Lock and Retention
• S3 Object Versioning
• S3 RenameObject
• S3 API Benchmark
• S3 API FAQ
• S3 Bucket Quota
• S3 Rate Limiting
• S3 API Audit log
• S3 Nginx Proxy
• Docker Compose for S3

S3 Table Bucket

• S3 Table Bucket
• S3 Table Bucket Commands
• S3 Tables Security
• SeaweedFS Iceberg Catalog
• Iceberg REST Catalog API
• Iceberg Table Maintenance
• SeaweedFS Lance Catalog
• Lance Maintenance Worker

Iceberg Integrations

• Spark Iceberg Integration
• Trino Iceberg Integration
• Dremio Iceberg Integration
• DuckDB Iceberg Integration
• Doris Iceberg Integration
• RisingWave Iceberg Integration
• Lakekeeper Iceberg Integration

Lance Integrations

• LanceDB Integration
• Spark Lance Integration
• DuckDB Lance Integration

S3 Authentication & IAM

• S3 Configuration - Start Here
• S3 Credentials (-s3.config)
• OIDC Integration (-s3.iam.config)
• Kubernetes ServiceAccount Authentication (IRSA-style)
• S3 Policy Variables
• S3 Policy Conditions
• S3 Bucket Policies
• Amazon IAM API
• AWS IAM CLI
• weed shell - Shell IAM Commands

Server-Side Encryption

• Server-Side Encryption
• Server-Side Encryption SSE-KMS
• Server-Side Encryption SSE-C

S3 Client Tools

• AWS CLI with SeaweedFS
• s3cmd with SeaweedFS
• rclone with SeaweedFS
• restic with SeaweedFS
• nodejs with Seaweed S3

Machine Learning

• TensorFlow with SeaweedFS
• Distributing AI Model Files for Multi-GPU Loading

HDFS

• Hadoop Compatible File System
• run Spark on SeaweedFS
• run HBase on SeaweedFS
• Run Trino on SeaweedFS
• Hadoop Benchmark
• HDFS via S3 connector

Replication and Backup

• Async Replication to another Filer [Deprecated]
• Async Backup
• Async Filer Metadata Backup
• Async Replication to Cloud [Deprecated]
• Kubernetes Backups and Recovery with K8up

Metadata Change Events

• Filer Metadata Events
• Filer Notification Webhook

Messaging

• Structured Data Lake with SMQ and SQL
• Seaweed Message Queue
• SQL Queries on Message Queue
• SQL Quick Reference
• PostgreSQL-compatible Server weed db
• Pub-Sub to SMQ to SQL
• Kafka to Kafka Gateway to SMQ to SQL

Use Cases

• Use Cases
• Actual Users

Operations

• System Metrics
• weed shell
• Data Backup
• Deployment to Kubernetes and Minikube
• Helm Chart Recipes
• Deployment with seaweed-up
  • seaweed-up Command Reference
  • Cluster Plan Workflow
  • Cluster Plan Inventory Reference
  • Cluster Plan Day 2 Operations

Rust Volume Server

• Rust Volume Server

Advanced

• Large File Handling
• Optimization
• Optimization for Many Small Buckets
• Volume Management
• Tiered Storage
• Cloud Tier
• Cloud Monitoring
• Load Command Line Options from a file
• SRV Service Discovery
• Volume Files Structure

Security

• Security Overview
• Security Configuration
• Cryptography and FIPS Compliance
• Run Blob Storage on Public Internet

Misc Use Case Examples

• UrBackup with SeaweedFS
• Docker Image Registry with SeaweedFS
• SeaweedFS in Docker Swarm
• Words from SeaweedFS Users
• Independent Benchmarks
• Hardware