Incompatibilities With AWS S3

This section documents key incompatibilities between versitygw and AWS S3. Most of these differences relate to legacy AWS S3 behaviors that versitygw does not currently implement and may not implement unless there is a strong use case or community demand.

BucketAlreadyOwnedByYou behavior in us-east-1

AWS S3 behavior (legacy): In most regions, attempting to create a bucket that already exists and is owned by you returns the BucketAlreadyOwnedByYou error. In us-east-1, AWS S3 historically behaves differently: recreating an existing bucket you already own can return 200 OK and may reset the bucket ACLs (legacy compatibility behavior).

Versitygw behavior: versitygw does not implement the special-case legacy behavior for us-east-1. Attempting to create a bucket that already exists and is owned by the same account returns BucketAlreadyOwnedByYou (error) in us-east-1 as well.

Reference: AWS docs

Bucket ACLs

Bucket ACLs are supported, but their behavior differs from AWS S3 in some cases. The details are documented here:

• Differences from AWS S3

Recommendation: Prefer bucket policies for all bucket- and object-level access control requirements, and treat ACL support as compatibility-oriented rather than a primary access control model.

Object ACLs

AWS S3 behavior: AWS S3 supports object ACLs, allowing permissions to be applied per-object (in addition to bucket policies, IAM, etc.).

Versitygw behavior: versitygw currently does not support object ACLs. Any ACL-like behavior is effectively managed at the bucket level, and bucket-level permissions apply across objects within that bucket.

Impact / notes:

• Object ACL headers are ignored for incoming requests.
• Use bucket policies / bucket ACLs(less recommended) instead of object ACLs.

AWS Signature Version 2 (SigV2) Authentication

AWS S3 behavior: AWS S3 historically supported both Signature Version 2 (SigV2) and Signature Version 4 (SigV4) for request authentication. SigV2 is a legacy authentication scheme.

Versitygw behavior: versitygw does not support AWS Signature Version 2 (SigV2). Only Signature Version 4 (SigV4) is supported for authenticating requests.

Impact / notes:

• Clients configured to use SigV2 will receive the following error:
  • HTTP 400 Bad Request with error code InvalidRequest and message: "The authorization mechanism you have provided is not supported. Please use AWS4-HMAC-SHA256."
• Ensure your S3 client or SDK is configured to use SigV4 (this is the default in all modern AWS SDKs).
• AWS itself deprecated SigV2 support for new regions and many services; all current AWS SDKs default to SigV4.

Reference: AWS SigV4 documentation

Non-AWS Error Codes (POSIX/ScoutFS Backend)

versitygw defines several error codes that have no equivalent in the AWS S3 API. These are returned exclusively by the POSIX (and ScoutFS) backend when filesystem-level conditions arise that have no direct S3 analogue. S3 clients that inspect error codes may need to handle these explicitly.

Error Code	HTTP Status	Description	When returned
ExistingObjectIsDirectory	409 Conflict	The target key maps to a path that already exists as a directory in the filesystem.	PutObject or CopyObject where the object key matches an existing directory.
ObjectParentIsFile	409 Conflict	A path component in the object key already exists as a regular file, so the required parent directory cannot be created.	PutObject or CopyObject where an intermediate path component in the key exists as a file rather than a directory.
DirectoryObjectContainsData	400 Bad Request	An object key ending in / (directory object) was submitted with a non-zero content body, or a multipart upload was initiated for a key ending in /.	PutObject with a trailing / key and a non-zero Content-Length, or CreateMultipartUpload with a trailing / key.
ErrDirectoryNotEmpty	400 Bad Request	Attempted to delete a directory object that still has children beneath it in the filesystem.	DeleteObject on a key that maps to a non-empty directory.
QuotaExceeded	403 Forbidden	The filesystem user quota has been exceeded (EDQUOT).	Write operations (PutObject, UploadPart, UploadPartCopy, CompleteMultipartUpload) when the filesystem reports a quota violation.
InsufficientStorage	507 Insufficient Storage	The underlying filesystem has no space remaining (ENOSPC).	Write operations (PutObject, UploadPart, UploadPartCopy, CompleteMultipartUpload) or metadata writes when the filesystem is full.
VersioningNotConfigured	501 Not Implemented	A versioning-related API was called but the gateway was started without the --versioning-dir option.	PutBucketVersioning, GetBucketVersioning, or ListObjectVersions when versioning support has not been configured.
AccessControlListNotSupported	400 Bad Request	ACL operations are disabled at the gateway level via the --disable-acl flag.	PutBucketAcl when the gateway is running with --disable-acl.