[@payloadcms/ui] useUploadHandlers throws an error for seemingly no reason

[robinscholz]

Describe the Bug

We are currently trying to build a plugin for media uploads to different providers from within one collection (mux, s3) and are running into problems with payloads architecture.

The UploadHandlersProvider that is injected into the Layout seems to be not ready when our plugin is called. We have essentially modeled our code exactly like the storage-s3 plugin, but for whatever reason we are running into the same error message:

useUploadHandlers must be used within UploadHandlersProvider

The error stems from here:

payload/packages/ui/src/providers/UploadHandlers/index.tsx

Line 44 in b965db8

export const useUploadHandlers = (): UploadHandlersContext => {

The function is called here:

payload/packages/plugin-cloud-storage/src/client/createClientUploadHandler.tsx

Line 39 in b965db8

const { setUploadHandler } = useUploadHandlers()

This seems to be the official function to use for creating the necessary components. At least it is used by all the storage plugins.

Sadly we aren’t to knowledgeable about React 19 and React.use(), but it seems like this might be some sort of running condition where a plugin is initialised and thus the function called before the UploadHandlersProvider is able to provide the necessary context. From what I can gather a <Suspense> component should be present somewhere to deal with React.use() returning null? The error seems somewhat aggressive, given the fact that Payloads architecture should provide the correct structure for this to work seamlessly out of the box.

We’ve been digging for quite some time now, but can’t figure it out. It would be great if someone could either point us in the right direction, or if this really is a bug within payload, take a look and work on fixing this.

Link to the code that reproduces this issue

private repo, happy to invite someone

Reproduction Steps

See above

Which area(s) are affected? (Select all that apply)

plugin: cloud-storage

Environment Info

Binaries:
  Node: 20.18.3
  npm: 10.8.2
  Yarn: 1.22.19
  pnpm: 10.14.0
Relevant Packages:
  payload: 3.49.1
Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 24.5.0: Tue Apr 22 19:54:49 PDT 2025; root:xnu-11417.121.6~2/RELEASE_ARM64_T6000
  Available memory (MB): 32768
  Available CPU cores: 10

[github-actions]

Please add a reproduction in order for us to be able to investigate.

Depending on the quality of reproduction steps, this issue may be closed if no reproduction is provided.

Why was this issue marked with the invalid-reproduction label?

To be able to investigate, we need access to a reproduction to identify what triggered the issue. We prefer a link to a public GitHub repository created with create-payload-app@latest -t blank or a forked/branched version of this repository with tests added (more info in the reproduction-guide).

To make sure the issue is resolved as quickly as possible, please make sure that the reproduction is as minimal as possible. This means that you should remove unnecessary code, files, and dependencies that do not contribute to the issue. Ensure your reproduction does not depend on secrets, 3rd party registries, private dependencies, or any other data that cannot be made public. Avoid a reproduction including a whole monorepo (unless relevant to the issue). The easier it is to reproduce the issue, the quicker we can help.

Please test your reproduction against the latest version of Payload to make sure your issue has not already been fixed.

I added a link, why was it still marked?

Ensure the link is pointing to a codebase that is accessible (e.g. not a private repository). "example.com", "n/a", "will add later", etc. are not acceptable links -- we need to see a public codebase. See the above section for accepted links.

Useful Resources

• Reproduction Guide
• Contributing to Payload

[robinscholz]

This seems related:

https://stackoverflow.com/questions/79487931/issues-integrating-s3storage-plugin-in-payloadcms

[robinscholz]

The reproduction can be found here: https://github.com/magicasaservice/payload-plugins-bug
I'll happily provide an .env file if needed!

[robinscholz]

Another related bug it seems: #11991

[robinscholz]

Another one: #11717

[robinscholz]

We have now figured out that running pnpm store prune temporarily solves this issue every time it reoccurs. I’d still be interested to know what’s causing it. If it can’t be fixed, maybe the error message could at least be a more descriptive.

[sannajammeh]

@robinscholz This is a depdendency issue. If you're using pnpm you need to public hoist @payloadcms/* inside your .npmrc.
There's a bug inside of @payloadcms/plugin-cloud-storage marking @payloadcms/ui as depdendency rather than peer dependency. Hence duplicate node_modules.

See the following screenshot for the issue:

@jmikrut Not sure who to tag here, 3.50.0 is currently unusable with cloud storage plugin enabled (npm & bun) - pnpm works as its resolution logic correctly hoists @payloadcms/ui