pdf.js warns 'Setting up fake worker' when a PDF opens in a React app
Warning: Setting up fake worker.Short answer
pdf.js normally parses PDFs in a web worker. The warning means it could not start that worker and is running the same code on the main thread, which is slower and can freeze the page. Set GlobalWorkerOptions.workerSrc to a worker file of the exact same pdfjs-dist version, in the module that renders the PDF.
Fix it fast
1Find out which cause you have
Open the browser Network tab and filter by worker. Either no request for the worker file appears, or it fails with a 404 or an error. That one fact separates the causes below.
npm ls pdfjs-dist react-pdf2Match what you see, then jump to its fix
- 1
No "GlobalWorkerOptions.workerSrc" specified.workerSrc was never setFix - 2
The worker request succeeds or fails and a version mismatch message followsThe worker version differs from the pdf.js library versionFix - 3
workerSrc exists in the project, the warning still showsworkerSrc is set in a different module than the componentsFix - 4
The warning or a worker error appears while the page is rendered on the serverThe viewer renders on the server in Next.jsFix
- 1
What does the error look like?
Warning: Setting up fake worker.Setting up fake worker failed: "...".No "GlobalWorkerOptions.workerSrc" specified.
Cause 1 of 4
workerSrc was never set
1Check
pdf.js reads GlobalWorkerOptions.workerSrc when it creates the worker. When it is empty, the call throws that message, and the library falls back to loading the worker on the main thread, which also needs the path.
grep -rn "workerSrc" src/2Fix
Set it once, with a URL that your bundler resolves to the worker file of the installed pdfjs-dist.
import { pdfjs } from "react-pdf";
pdfjs.GlobalWorkerOptions.workerSrc = new URL(
"pdfjs-dist/build/pdf.worker.min.mjs",
import.meta.url,
).toString();3Verify
Reload the page; the worker file shows up in the Network tab and the warning is gone.
grep -rn "workerSrc" src/Confirmed by github.com
Cause 2 of 4
The worker version differs from the pdf.js library version
1Check
The worker must match the pdfjs-dist version that react-pdf uses. A second pdfjs-dist install, or a worker file copied by hand or taken from a CDN of another version, breaks that.
npm ls pdfjs-dist
grep -rn "pdf.worker" src/ public/2Fix
Load the worker from the installed package, not from a copy, or from a CDN URL that uses the library's own version number. If you installed pdfjs-dist yourself, pin it to the version react-pdf depends on.
pdfjs.GlobalWorkerOptions.workerSrc =
`//unpkg.com/pdfjs-dist@${pdfjs.version}/build/pdf.worker.min.mjs`;3Verify
Open a PDF and check that the console shows no version message.
npm ls pdfjs-distConfirmed by github.com
Cause 3 of 4
workerSrc is set in a different module than the components
1Check
react-pdf requires the assignment in the same module where Document and Page are used.
grep -rln "workerSrc\|<Document" src/2Fix
Move the workerSrc line into the file that imports Document and Page.
// PdfViewer.tsx
import { Document, Page, pdfjs } from "react-pdf";
pdfjs.GlobalWorkerOptions.workerSrc = new URL(
"pdfjs-dist/build/pdf.worker.min.mjs",
import.meta.url,
).toString();3Verify
Reload and open the PDF.
grep -rln "workerSrc" src/Confirmed by github.com
Cause 4 of 4
The viewer renders on the server in Next.js
1Check
The worker setup uses browser APIs. react-pdf says to skip server rendering for the module that contains it.
grep -rn "react-pdf" app/ src/2Fix
Import the viewer component dynamically with SSR turned off.
import dynamic from "next/dynamic";
const PdfViewer = dynamic(() => import("./PdfViewer"), { ssr: false });3Verify
Run the dev server and open the page.
npm run devConfirmed by github.com
How do I stop it coming back?
- Set workerSrc in the same file as your Document component, from the installed package.
- Keep one pdfjs-dist version in the lockfile, and update react-pdf and pdfjs-dist together.
- Never mix a locally bundled library with a worker from a CDN.
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