transloadit/uppy · error · Error

Component must be called within a UppyContextProvider

Error message

Component must be called within a UppyContextProvider

What it means

injectUppyContext fails when a headless component is used outside a <UppyContextProvider>, or when the provider rendered but its uppy prop was never set. The inject() of UppyContextSymbol returned a context with no uppy instance.

Source

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

        },
      })
    })

    onBeforeUnmount(() => {
      uppyEventAdapter?.cleanup()
    })

    return () => slots.default?.()
  },
})

export default UppyContextProvider

export function injectUppyContext(): NonNullableUppyContext {
  const ctx = inject<UppyContext>(UppyContextSymbol)

  if (!ctx?.uppy) {
    throw new Error('Component must be called within a UppyContextProvider')
  }

  return ctx as NonNullableUppyContext // covered by the if-statement above
}

View on GitHub (pinned to 5d4dedd02a)

Solutions

1. Wrap the component tree containing headless components in <UppyContextProvider :uppy="uppy">
2. Ensure only one provider instance and that the components are its descendants

Example fix

// before
<FileInput /> <!-- no provider ancestor -->
// after
<UppyContextProvider :uppy="uppy"><FileInput /></UppyContextProvider>

// ensure component tree is inside provider
// <UppyContextProvider :uppy="uppy"> ...headless components... </UppyContextProvider>

import { inject } from 'vue'
const insideProvider = (): boolean => inject(UppyContextSymbol, null)?.uppy != null

When it happens

Trigger: Using useFileInput()/any headless composable or component in a part of the Vue tree not wrapped by UppyContextProvider, or wrapped by a provider that never received an :uppy prop.

Common situations: Placing headless components in a different component than the provider; refactoring that accidentally removes the provider; multiple roots where the component sits outside the provided subtree.

Related errors

• UppyContextProvider: passing `uppy` as a prop is required
• Missing token payload for provider ${providerName}
• Received no remote credentials
• call to thumbnail is not implemented
• call to thumbnail is not implemented

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