Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

File uploads with UploadThing stop working after an upgrade in a Next.js app

ErrorUploads that worked on UploadThing v6 fail after upgrading to v7

Short 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.

  • Applies to uploadthing 7, Next.js 15, Next.js 16
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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/null
  2. 2Match what you see, then jump to its fix

    1. 1grep shows UPLOADTHING_SECRET (and maybe an app id), but no UPLOADTHING_TOKENThe project still sets UPLOADTHING_SECRETFix
    2. 2The build or editor flags '@uploadthing/react/hooks', generateComponent, createNextRouteHandler or permittedFileInfoImports or helpers that v7 removedFix
    3. 3The error shows up where UploadButton or UploadDropzone is rendered inside a file with no use client directiveUploadButton is rendered from a Server ComponentFix

What does the error look like?

  • Uploads that worked on UploadThing v6 fail after upgrading to v7
  • An import from '@uploadthing/react/hooks' stops working after the upgrade
  • Code that imports generateComponent or createNextRouteHandler no longer works
  • UploadButton 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=.next

2Fix

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 dev

Confirmed by docs.uploadthing.com

Did this fix it?

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=.next

2Fix

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 build

Confirmed by docs.uploadthing.com

Did this fix it?

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 components

2Fix

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 dev

Confirmed by docs.uploadthing.com

Did this fix it?

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:

Related fixes

Web 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 fix

Web 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

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.