File uploads with UploadThing stop working after an upgrade in a Next.js app
Uploads that worked on UploadThing v6 fail after upgrading to v7Short answer
UploadThing v7 changed its setup. The server now reads one UPLOADTHING_TOKEN variable instead of the old secret, several old entrypoints and helper names were removed, and components that render UploadButton must be Client Components. Compare the project with the v7 migration guide in that order.
Fix it fast
1Find out which cause you have
Check which versions are installed and which UploadThing variable the project defines. A project on v7 that only has the old secret variable is the most common mismatch.
npm ls uploadthing @uploadthing/react grep -n "UPLOADTHING" .env* 2>/dev/null2Match what you see, then jump to its fix
- 1
grep shows UPLOADTHING_SECRET (and maybe an app id), but no UPLOADTHING_TOKENThe project still sets UPLOADTHING_SECRETFix - 2
The build or editor flags '@uploadthing/react/hooks', generateComponent, createNextRouteHandler or permittedFileInfoImports or helpers that v7 removedFix - 3
The error shows up where UploadButton or UploadDropzone is rendered inside a file with no use client directiveUploadButton is rendered from a Server ComponentFix
- 1
What does the error look like?
Uploads that worked on UploadThing v6 fail after upgrading to v7An import from '@uploadthing/react/hooks' stops working after the upgradeCode that imports generateComponent or createNextRouteHandler no longer worksUploadButton fails when it is rendered from a Server Component
Cause 1 of 3
The project still sets UPLOADTHING_SECRET
1Check
In v7 the server needs to know more about the app, so the required information is merged into a single UPLOADTHING_TOKEN variable. Config keys such as uploadthingSecret and uploadthingAppId were replaced by token.
grep -rn "UPLOADTHING_SECRET\|uploadthingSecret\|uploadthingAppId" . --include=".env*" --include="*.ts" --include="*.tsx" --exclude-dir=node_modules --exclude-dir=.next2Fix
Open the UploadThing Dashboard, go to API Keys, select the V7 tab, and copy the token into your environment under the new name. Remove the old variable and any old config keys.
# .env.local
UPLOADTHING_TOKEN='paste-the-token-from-the-V7-tab'3Verify
Start the app again and upload one small file through your UploadButton.
npm run devConfirmed by docs.uploadthing.com
Cause 2 of 3
Imports or helpers that v7 removed
1Check
The v7 guide lists these as removed. The hooks entrypoint is gone, generateComponent is no longer exported, every adapter exports createRouteHandler, and useUploadThing no longer returns permittedFileInfo.
grep -rn "uploadthing/react/hooks\|generateComponent\|createNextRouteHandler\|permittedFileInfo" . --include="*.ts" --include="*.tsx" --exclude-dir=node_modules --exclude-dir=.next2Fix
Import from the main entrypoint, use generateUploadButton and generateUploadDropzone, build the route with createRouteHandler, and read routeConfig instead of permittedFileInfo. The Next.js adapter still returns named GET and POST exports.
// app/api/uploadthing/route.ts
import { createRouteHandler } from 'uploadthing/next'
import { ourFileRouter } from './core'
export const { GET, POST } = createRouteHandler({ router: ourFileRouter })
// src/utils/uploadthing.ts
import { generateReactHelpers, generateUploadButton, generateUploadDropzone } from '@uploadthing/react'3Verify
Run a type check and a build to catch any import that is still left.
npx tsc --noEmit && npm run buildConfirmed by docs.uploadthing.com
Cause 3 of 3
UploadButton is rendered from a Server Component
1Check
The UploadThing Next.js guide says components that render UploadButton need the use client directive, since the button runs on the client.
grep -rln "UploadButton\|UploadDropzone" app src components2Fix
Put the directive at the top of the file that renders the button, before any imports.
'use client'
import { UploadButton } from '@/utils/uploadthing'
export function Uploader() {
return <UploadButton endpoint="imageUploader" />
}3Verify
Open the page that shows the button and pick a file.
npm run devConfirmed by docs.uploadthing.com
How do I stop it coming back?
- Read the breaking-changes list of a library's migration guide before raising its major version.
- Upgrade uploadthing and @uploadthing/react in the same commit, and test one upload before you merge.
- Keep the token in environment variables, never in source files that are committed.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- TaskvareA task and project-management suite: React on the web, Flutter on mobile, TypeScript underneath.
Related fixes
Web apps
ESLint says an element in a list is missing its key prop
react/jsx-key
react/jsx-key fires when an element returned from map, Array.from or an array literal has no key.
3 causes, each with a fixWeb apps
There is no tailwind.config.js after installing Tailwind 4 and HeroUI in Next.js
HeroUI components render unstyled
Nothing is broken: Tailwind CSS 4 is configured in CSS and no longer creates tailwind.config.js.
3 causes, each with a fixWeb apps
react-i18next shows the wrong plural form for a count, or prints the key instead of the text
t('item') prints the key item instead of a translated sentence
i18next picks a plural from the count option and looks for keys ending in _one, _other and so on.
4 causes, each with a fixWeb apps
useSession throws because there is no SessionProvider above it
[next-auth]: `useSession` must be wrapped in a <SessionProvider />
useSession reads the session from React Context, and SessionProvider is what creates that context.
3 causes, each with a fixWeb apps
next/link throws React.Children.only on its children
Error: React.Children.only expected to receive a single React element child.
React.Children.only accepts exactly one React element and throws for anything else, including an array with one item.
3 causes, each with a fixWeb apps
Hydration failed after adding next-themes dark mode
Console reports a server and client mismatch on the html element
next-themes changes the html element and knows the theme only in the browser, so server HTML and client HTML differ.
3 causes, each with a fix