Maaz Zindani

Loading the index…

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

pdf.js warns 'Setting up fake worker' when a PDF opens in a React app

ErrorWarning: 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.

  • Applies to react-pdf 9 to 10, pdfjs-dist, React 19, Vite, Next.js 15
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

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

    1. 1No "GlobalWorkerOptions.workerSrc" specified.workerSrc was never setFix
    2. 2The worker request succeeds or fails and a version mismatch message followsThe worker version differs from the pdf.js library versionFix
    3. 3workerSrc exists in the project, the warning still showsworkerSrc is set in a different module than the componentsFix
    4. 4The warning or a worker error appears while the page is rendered on the serverThe viewer renders on the server in Next.jsFix

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

Did this fix it?

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-dist

Confirmed by github.com

Did this fix it?

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

Did this fix it?

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 dev

Confirmed by github.com

Did this fix it?

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:

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.