Error states

Show a clear message with Retry when a document can't load or render, and receive a typed error for your own handling.

Basics

When a document fails to load, the viewer shows an alert with a Retry button and keeps the toolbar usable.

import { PdfViewer } from '@kingtech/react-pdf-viewer'; export default function Demo() { return <PdfViewer source="/samples/does-not-exist.pdf" />; }

The toolbar stays so that fullscreen can always be left. Aborted loads and canceled renders are never reported as errors.

Failure types

Every failure reaches onError as a PdfViewerError with a machine-readable code, a readable message, the HTTP status where there is one, and the original cause.

import { PdfViewer, type PdfViewerError } from '@kingtech/react-pdf-viewer'; import { useState } from 'react'; const CASES = { 'Missing file (404)': '/samples/does-not-exist.pdf', 'Not a PDF': '/samples/not-a-pdf.pdf', 'Password protected': '/samples/password.pdf', 'Blocked by CORS': 'https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf', }; type Case = keyof typeof CASES; export default function Demo() { const [current, setCurrent] = useState<Case>('Missing file (404)'); const [error, setError] = useState<PdfViewerError | null>(null); return ( <> <p className="demo-controls"> <label> Failure{' '} <select value={current} onChange={(event) => { setCurrent(event.target.value as Case); setError(null); }} > {Object.keys(CASES).map((name) => ( <option key={name}>{name}</option> ))} </select> </label> </p> <PdfViewer key={current} source={CASES[current]} onError={setError} /> <pre className="demo-output" aria-label="onError payload"> {error ? JSON.stringify( { code: error.code, status: error.status, message: error.message }, null, 2, ) : 'onError not called yet'} </pre> </> ); }

Code	When
`PDFJS_LOAD_FAILED`	The `pdfjs-dist` module or its worker failed to load.
`NETWORK_ERROR`	`fetch` rejected: offline, CORS, DNS, …
`HTTP_ERROR`	The server answered with a non-2xx status (`status` is set).
`INVALID_PDF`	The bytes are not a valid PDF.
`PASSWORD_REQUIRED`	The document is encrypted and no password was supplied.
`INCORRECT_PASSWORD`	The supplied password is wrong.
`RENDER_FAILED`	A page failed to render.
`DOWNLOAD_FAILED`	Saving the document failed.
`PRINT_FAILED`	Printing failed.
`UNKNOWN`	Anything else.

Generated from the source; see the PdfViewerErrorCode reference.

RENDER_FAILED replaces only the page that failed; the password codes are covered in Password protection.

Reporting errors

<PdfViewer
  source={url}
  onError={(error) =>
    logger.warn('pdf-viewer', error.code, { status: error.status, cause: error.cause })
  }
/>

HTTP errors that onHttpError handles (for example a 401 that redirects to sign-in) are not reported; see Authenticated requests.

Customization

renderError(error, { retry }) replaces the error view for document and page errors.

import { PdfViewer } from '@kingtech/react-pdf-viewer'; export default function Demo() { return ( <PdfViewer source="/samples/does-not-exist.pdf" renderError={(error, { retry }) => ( <div role="alert" style={{ padding: 24, border: '1px solid #fca5a5', borderRadius: 12 }}> <strong>We couldn’t open this document.</strong> <p> {error.code === 'HTTP_ERROR' && error.status === 404 ? 'It may have been moved or deleted.' : error.message} </p> <button type="button" onClick={retry}> Try again </button> </div> )} /> ); }

Colors of the default view are CSS variables (--rpv-error-bg, --rpv-error-fg, --rpv-error-icon); see the customization guide.

Advanced / escape hatch

reload() on the imperative API retries from anywhere in your app. With usePdfDocument, error and reload are returned directly.

Limitations

Messages are in English by default. HTTP_ERROR messages come from getHttpErrorMessage, which reads RFC 7807 bodies; other codes carry English messages. Workaround: map error.code to your own text in renderError.
CORS failures are indistinguishable from offline. Browsers do not tell scripts why a cross-origin request failed, so both appear as NETWORK_ERROR. Workaround: explain both possibilities in your error view, as the demo above does.

API

PdfViewerError — A typed viewer error. Aborted loads and canceled renders are never reported as errors.
PdfViewerErrorCode — Machine-readable category of a PdfViewerError, for handling failures such as a missing password or an HTTP error in code.