Use upload sessions to avoid orphaned files in cloud storage

[klaatu-code]

Describe the Bug

With clientUploads: true, a file is written to S3-compatible storage before Payload creates the upload collection document. If Payload's server-side content detection later rejects that file, the collection request correctly returns 400 and no database document is created, but the already-uploaded cloud object remains at its final key.

This is easiest to reproduce with a text or JSON file renamed to .jpg:

• the browser sees a .jpg and requests a signed upload URL;
• the signed URL request succeeds;
• the direct PUT to object storage succeeds;
• POST /api/media then returns 400 with File type text/plain (from extension jpg) is not allowed.;
• no media document exists, but the .jpg object is still present in the bucket.

The validation itself is working as intended. The problem is that the rejected client upload is not rolled back.

In a real editorial workflow, accidental or malformed uploads are fairly ordinary. Over time, every rejected direct upload can become a billable object that is invisible to Payload's database-backed media management and normal delete flow. Upload permission is still required, so I would describe this as a storage lifecycle/resource-leak issue rather than a security vulnerability.

Source inspection suggests this occurs because the client upload is reconstructed into req.file, collection beforeOperation hooks run, and core file processing/content sniffing can throw later in generateFileData / checkFileRestrictions. The storage adapter does not appear to receive a rollback callback for that failure path.

Expected behavior: when a direct client upload is rejected before the upload document is committed, Payload (or the storage adapter contract) should best-effort delete the exact object identified by the client upload context.

Possible implementation directions could be:

• upload to a temporary key and promote only after the collection operation succeeds; or
• invoke adapter cleanup for the exact client-upload key when server-side validation or later create processing fails.

An application-level collection afterError hook can work around this by checking req.file.clientUploadContext and deleting the exact key, but generic cleanup in the client-upload/storage lifecycle would protect every upload collection and storage adapter consistently.

Link to the code that reproduces this issue

The official S3 client-upload test configuration is a suitable base:

https://github.com/payloadcms/payload/blob/v3.88.0/test/storage-s3/client-uploads/config.ts

Use an upload collection restricted to image MIME types and the reproduction steps below. The relevant v3.88.0 validation path is also visible in:

• https://github.com/payloadcms/payload/blob/v3.88.0/packages/payload/src/collections/operations/create.ts
• https://github.com/payloadcms/payload/blob/v3.88.0/packages/payload/src/uploads/checkFileRestrictions.ts

Reproduction Steps

1. Configure @payloadcms/storage-s3 with clientUploads: true against S3 or an S3-compatible provider.

2. Configure an upload collection with an image allowlist, for example:

   {
     slug: 'media',
     fields: [{ name: 'alt', type: 'text', required: true }],
     upload: {
       mimeTypes: ['image/jpeg', 'image/png', 'image/webp'],
     },
   }

3. Create a small text or JSON file and name it not-an-image.jpg.

4. In the admin panel, upload that file and fill any required fields.

5. Observe the request sequence:

   • signed URL request: 200;
   • object-storage PUT: 200;
   • upload collection POST: 400, with File type text/plain (from extension jpg) is not allowed.

6. Confirm that no upload collection document was created.

7. List the bucket at the configured prefix. not-an-image.jpg is still present at the final key.

Control case: a genuinely valid JPEG follows the same client-upload path, creates the document, and can later be removed through the normal Payload delete flow.

Which area(s) are affected?

• area: core
• plugin: cloud-storage
• plugin: storage-*

Environment Info

Payload: 3.88.0
@payloadcms/storage-s3: 3.88.0
Next.js: 16.2.12
React: 19.2.4
Node.js: 24.19.0
Database: PostgreSQL
Storage: S3-compatible object storage (Cloudflare R2)
Client uploads: enabled
Browser: Chrome

[paulpopus]

My current recommendation here is to implement your own cleanup logic until we build this into core.

I have design specs written up for "upload sessions" as a concept where we store any uploads in this temporary state, allowing us to also track, revert, resume or otherwise clean-up file uploads.

I'd categorise this as intended behaviour as it's a known limitation so I'll move it to a github discussion and mark it as a feature request, this fits well into our DAM project

[klaatu-code]

Thanks for clarifying, Paul — that makes sense.

We’ve implemented application-level cleanup for now using collection afterError hooks. The cleanup is gated on req.file.clientUploadContext, validates the expected prefix and filename, checks that the object is not already referenced by an upload document, and performs a best-effort delete without replacing the original validation error.

We verified the original reproduction case with a text file renamed to .jpg: Payload returns the expected 400, no upload document is created, and the object is removed from the S3-compatible storage.

We’ll keep this workaround in place until upload sessions or equivalent lifecycle cleanup lands in core. The upload sessions concept sounds like the right long-term abstraction, and we’d be happy to test it against an R2 + clientUploads workflow once there is a branch or PR available.

Thanks!