transloadit/uppy · error · Error

UppyContextProvider: passing `uppy` as a prop is required

Error message

UppyContextProvider: passing `uppy` as a prop is required

What it means

UppyContextProvider's setup throws in onMounted when no uppy prop was passed, because the Vue headless components require an Uppy instance provided at mount time to wire up the event adapter.

Source

Thrown at packages/@uppy/vue/src/headless/context-provider.ts:49

  },
  setup(props, { slots }) {
    const status = ref<UploadStatus>('init')
    const progress = ref(0)

    const uppyContext = reactive<UppyContext>({
      uppy: markRaw(props.uppy),
      status: 'init',
      progress: 0,
    })

    // Provide the context immediately instead of in onMounted
    provide(UppyContextSymbol, uppyContext)

    let uppyEventAdapter: ReturnType<typeof createUppyEventAdapter> | undefined

    onMounted(() => {
      if (!props.uppy) {
        throw new Error(
          'UppyContextProvider: passing `uppy` as a prop is required',
        )
      }

      uppyEventAdapter = createUppyEventAdapter({
        uppy: props.uppy,
        onStatusChange: (newStatus: UploadStatus) => {
          status.value = newStatus
          uppyContext.status = newStatus
        },
        onProgressChange: (newProgress: number) => {
          progress.value = newProgress
          uppyContext.progress = newProgress
        },
      })
    })

    onBeforeUnmount(() => {

View on GitHub (pinned to 5d4dedd02a)

Solutions

Pass the Uppy instance: <UppyContextProvider :uppy="uppy">
If the instance loads async, render the provider only once it exists: <UppyContextProvider v-if="uppy" :uppy="uppy"> or supply a default instance from composable useUppy()

Example fix

// before
<UppyContextProvider><FileInput /></UppyContextProvider>
// after
<UppyContextProvider :uppy="uppy"><FileInput /></UppyContextProvider>

Defensive patterns

Strategy: validation

Validate before calling

const uppy = useUppy() // ensure instance before render
// template: <UppyContextProvider v-if="uppy" :uppy="uppy">

Type guard

const hasUppyProp = (p: { uppy?: unknown }): p is { uppy: object } => p.uppy instanceof Object

Prevention

Create the Uppy instance eagerly in setup(), not lazily on mount
Gate the provider with v-if when the instance is async

When it happens

Trigger: Rendering <UppyContextProvider> without an :uppy prop (or with a prop that is undefined at mount), e.g. <UppyContextProvider> instead of <UppyContextProvider :uppy="uppy">.

Common situations: Vue 3 apps migrating to @uppy/vue headless components; uppy instance created asynchronously so the prop is initially undefined; forgetting the prop entirely.

Related errors

AI-assisted analysis of transloadit/uppy@5d4dedd02a (2026-08-28). Data as JSON: /api/errors/c5530401548a3afc. Report an issue: GitHub.