Use when handling PDF document loading failures, password-protected PDFs, corrupt files, or missing CMap/font data. Prevents unhandled exceptions by covering all PDF.js error types and their recovery patterns. Covers InvalidPDFException, MissingPDFException, PasswordException, network/CORS errors, CJK font issues, and corrupt PDF recovery strategies. Keywords: InvalidPDFException, MissingPDFException, PasswordException, CMap, CORS, corrupt PDF, PDF won't load, broken PDF, can't open PDF, password protected, PDF error.
Use when handling PDF document loading failures, password-protected PDFs, corrupt files, or missing CMap/font data. Prevents unhandled exceptions by covering all PDF.js error types and their recovery patterns. Covers InvalidPDFException, MissingPDFException, PasswordException, network/CORS errors, CJK font issues, and corrupt PDF recovery strategies. Keywords: InvalidPDFException, MissingPDFException, PasswordException, CMap, CORS, corrupt PDF, PDF won't load, broken PDF, can't open PDF, password protected, PDF error.
license
MIT
compatibility
Designed for Claude Code. Requires pdfjs-dist 5.x.
ALWAYS wrap getDocument().promise in a try/catch -- document loading can throw any of the exception types above, and unhandled rejections cause blank pages with no user feedback.
ALWAYS check the name property of caught errors to distinguish between InvalidPDFException, MissingPDFException, PasswordException, and UnknownErrorException -- each requires a different recovery strategy.
NEVER swallow document loading errors with an empty catch block -- the user sees a blank page with no indication of what went wrong.
ALWAYS configure cMapUrl and set cMapPacked: true when loading PDFs that may contain CJK (Chinese, Japanese, Korean) text -- without CMaps, CJK characters render as blank rectangles.
ALWAYS set standardFontDataUrl when using pdfjs-dist 5.x -- PDF.js needs access to standard font data files for proper text rendering of PDFs that reference standard 14 fonts.
NEVER retry a PasswordException with the same password -- it will fail again. ALWAYS prompt the user for a new password before retrying.
Diagnostic Decision Tree
PDF document fails to load?
|
+-- InvalidPDFException
| +-- File is 0 bytes? -> Download/upload failed, retry transfer
| +-- File starts with "%PDF"? -> PDF is corrupt or truncated, re-obtain file
| +-- File is actually HTML (404 page)? -> Server returned error page, fix URL
| +-- File is a different format (DOCX, image)? -> Not a PDF, convert first
|
+-- MissingPDFException
| +-- URL returns 404? -> Fix the URL path
| +-- File was deleted? -> Handle gracefully, show "file not found" message
| +-- Redirect to login page? -> Handle authentication before loading PDF
| +-- Using relative URL? -> Use absolute URL or correct base path
|
+-- PasswordException
| +-- code === PasswordResponses.NEED_PASSWORD? -> Prompt user for password
| +-- code === PasswordResponses.INCORRECT_PASSWORD? -> Show "wrong password", reprompt
| +-- Programmatic access needed? -> Pass password in getDocument({ password })
|
+-- Network / CORS error
| +-- Mixed content (HTTP PDF on HTTPS page)? -> Serve PDF over HTTPS
| +-- Cross-origin without CORS headers? -> Add CORS headers on PDF server
| +-- Proxy available? -> Route PDF through same-origin proxy
| +-- Fetch fails entirely? -> Check network, show offline message
|
+-- CJK text missing / blank characters
| +-- cMapUrl not set? -> Set cMapUrl to cmaps directory path
| +-- cMapPacked not true? -> Add cMapPacked: true to getDocument options
| +-- CMap files not deployed? -> Copy cmaps/ from pdfjs-dist to public dir
|
+-- Font rendering issues
| +-- standardFontDataUrl not set? -> Set path to standard_fonts directory
| +-- Embedded font broken? -> PDF issue, not fixable in viewer
| +-- Font files not deployed? -> Copy standard_fonts/ from pdfjs-dist
|
+-- Memory error / crash on large PDF
| +-- PDF > 100 MB? -> Enable range requests (disableRange: false)
| +-- Many high-res images? -> Reduce rendering scale
| +-- Mobile device? -> Limit concurrent page renders
|
+-- UnknownErrorException
+-- Check err.message for details -> May contain specific parser error
+-- Reproducible with other PDFs? -> Likely a code issue, not PDF issue
+-- Only this PDF? -> Likely a corrupt or unusual PDF structure
Essential Fixes
Fix 1: InvalidPDFException -- Corrupt or Non-PDF File
Error: InvalidPDFException: Invalid PDF structure
Cause: The loaded data is not a valid PDF. Common when a server returns an HTML error page instead of the PDF file, or the file is truncated.
import { getDocument, GlobalWorkerOptions } from"pdfjs-dist";
GlobalWorkerOptions.workerSrc = newURL(
"pdfjs-dist/build/pdf.worker.min.mjs",
import.meta.url
).toString();
asyncfunctionloadPdfSafely(source: string | ArrayBuffer) {
try {
const doc = awaitgetDocument(
typeof source === "string" ? { url: source } : { data: source }
).promise;
return doc;
} catch (err: unknown) {
if (err instanceofError && err.name === "InvalidPDFException") {
thrownewError(
"The file is not a valid PDF. It may be corrupt, truncated, " +
"or the server returned an error page instead of the PDF file."
);
}
throw err;
}
}
Prevention: ALWAYS validate that the server response has Content-Type: application/pdf before passing data to getDocument(). If loading from user upload, check that the file starts with the %PDF magic bytes.
Fix 2: MissingPDFException -- File Not Found
Error: MissingPDFException: Missing PDF file.
Cause: The URL returned a 404 or the fetch failed entirely.
import { getDocument, GlobalWorkerOptions } from"pdfjs-dist";
GlobalWorkerOptions.workerSrc = newURL(
"pdfjs-dist/build/pdf.worker.min.mjs",
import.meta.url
).toString();
asyncfunctionloadPdfWithNotFoundHandling(url: string) {
try {
returnawaitgetDocument({ url }).promise;
} catch (err: unknown) {
if (err instanceofError && err.name === "MissingPDFException") {
thrownewError(
`PDF file not found at "${url}". ` +
"Verify the URL is correct and the file exists on the server."
);
}
throw err;
}
}
Fix 3: PasswordException -- Password-Protected PDF
Error: PasswordException with code: PasswordResponses.NEED_PASSWORD
Cause: The PDF is encrypted and requires a password to open.
import {
getDocument,
GlobalWorkerOptions,
PasswordResponses,
} from"pdfjs-dist";
GlobalWorkerOptions.workerSrc = newURL(
"pdfjs-dist/build/pdf.worker.min.mjs",
import.meta.url
).toString();
asyncfunctionloadPasswordProtectedPdf(url: string,
promptForPassword: () => Promise<string | null>
) {
// First attempt: load without passwordtry {
returnawaitgetDocument({ url }).promise;
} catch (err: unknown) {
if (!(err instanceofError) || err.name !== "PasswordException") {
throw err;
}
// PDF requires a password -- prompt userconst typedErr = err asError & { code: number };
if (typedErr.code === PasswordResponses.NEED_PASSWORD ||
typedErr.code === PasswordResponses.INCORRECT_PASSWORD) {
const password = awaitpromptForPassword();
if (!password) thrownewError("Password required but not provided.");
// Retry with passwordtry {
returnawaitgetDocument({ url, password }).promise;
} catch (retryErr: unknown) {
if (retryErr instanceofError &&
retryErr.name === "PasswordException") {
thrownewError("Incorrect password. Unable to open the PDF.");
}
throw retryErr;
}
}
throw err;
}
}
Fix 4: CORS / Network Errors
Error: Failed to fetch or Access to fetch blocked by CORS policy
Cause: The PDF is hosted on a different origin without CORS headers, or the page uses HTTPS while the PDF is served over HTTP (mixed content).
import { getDocument, GlobalWorkerOptions } from"pdfjs-dist";
GlobalWorkerOptions.workerSrc = newURL(
"pdfjs-dist/build/pdf.worker.min.mjs",
import.meta.url
).toString();
// SOLUTION 1: Load through a same-origin proxyasyncfunctionloadPdfViaProxy(externalUrl: string) {
const proxyUrl = `/api/pdf-proxy?url=${encodeURIComponent(externalUrl)}`;
returnawaitgetDocument({ url: proxyUrl }).promise;
}
// SOLUTION 2: Fetch as ArrayBuffer with custom headersasyncfunctionloadPdfWithFetch(url: string) {
const response = awaitfetch(url, {
mode: "cors",
credentials: "omit",
});
if (!response.ok) {
thrownewError(`Failed to fetch PDF: ${response.status}${response.statusText}`);
}
const data = await response.arrayBuffer();
returnawaitgetDocument({ data }).promise;
}
Fix 5: Missing CMap Data for CJK Text
Error: CJK characters appear as blank rectangles or tofu characters.
Cause: PDF.js needs CMap (Character Map) files to decode CJK-encoded text. Without them, characters in Chinese, Japanese, or Korean PDFs render incorrectly.
Prevention: ALWAYS set cMapUrl and cMapPacked: true in getDocument() options. The CMap files are included in the pdfjs-dist/cmaps/ directory. For production, copy the cmaps/ directory to your public assets folder.
Fix 6: Font Loading Failures
Error: Text renders with wrong glyphs, missing characters, or falls back to default fonts.
Cause: PDF.js needs standard font data files for PDFs that reference the standard 14 PDF fonts without embedding them.
