Error Reference

This guide documents all error types in the VerifyKit SDK, when they occur, and how to handle them.

LoadError

The LoadError interface is the primary error type for PDF loading and verification failures. It is returned by useVerification() in React and thrown by the core API.

interface LoadError {
  /** Semantic error type for programmatic handling */
  name: LoadErrorName
  /** Human-readable error message */
  message: string
}

The name property is one of the following LoadErrorName values:

Error Classification

The classifyPdfError() function converts unknown errors into typed LoadError objects. It preserves PDF.js exception names where applicable:

import { classifyPdfError } from '@trexolab/verifykit-react'
 
try {
  await verifier.verify(input)
} catch (err) {
  const loadError = classifyPdfError(err)
  console.log(loadError.name)    // e.g., 'InvalidPDFException'
  console.log(loadError.message) // e.g., 'Invalid PDF structure'
}

The preserved PDF.js exception names are:

• InvalidPDFException
• MissingPDFException
• UnexpectedResponseException
• PasswordException
• AbortException
• FormatError

Any error whose name property does not match one of these is classified as UnknownErrorException.

Creating Errors Programmatically

Use createLoadError() to construct a LoadError with a specific type:

import { createLoadError } from '@trexolab/verifykit-react'
 
const error = createLoadError('NetworkError', 'Failed to fetch AIA certificate')

When Errors Occur

PDF Parsing Errors

These errors occur during the initial PDF loading phase, before verification begins.

Password Errors

In the React viewer, a PasswordDialog is shown automatically. In headless mode, catch this error and prompt the user.

WASM Initialization Errors

WASM errors typically occur on the first call to createVerifier(). Common causes:

1. CSP blocks WASM. Add 'wasm-unsafe-eval' to your script-src directive.
2. Corrupt WASM binary. If using wasmUrl, ensure the file is served correctly with application/wasm MIME type.

Network Errors

Network errors can occur during:

• AIA resolution: Fetching intermediate certificates from URLs in the certificate chain. Disable with enableAIA: false.
• Revocation checking: OCSP/CRL requests via the revocation plugin proxy.
• URL-based PDF loading: When passing a URL string as input to verify() or load().

Verification Errors

This error indicates a problem with the signature structure inside the PDF (e.g., malformed CMS container, unsupported signature algorithm). It is distinct from a signature that verifies as invalid -- an invalid result means verification completed successfully but the signature did not pass checks.

Handling Errors in React

useVerification Error State

The useVerification() hook exposes an error property of type LoadError | null:

import { useVerification } from '@trexolab/verifykit-react'
 
function MyViewer() {
  const { load, error, isLoading, result } = useVerification()
 
  if (error) {
    switch (error.name) {
      case 'InvalidPDFException':
        return <p>This file is not a valid PDF.</p>
      case 'PasswordException':
        return <p>This PDF requires a password.</p>
      case 'NetworkError':
        return <p>Network error: {error.message}</p>
      default:
        return <p>Error: {error.message}</p>
    }
  }
 
  if (isLoading) {
    return <p>Loading...</p>
  }
 
  // Render viewer or results
}

Error Boundary

VerifyKit exports a PdfViewerErrorBoundary component for catching unexpected rendering errors:

import { PdfViewerErrorBoundary, Viewer } from '@trexolab/verifykit-react'
 
<PdfViewerErrorBoundary>
  <Viewer fileBuffer={buffer} plugins={plugins} />
</PdfViewerErrorBoundary>

Handling Errors in Headless Mode

When using @trexolab/verifykit-core directly, use try/catch:

import { createVerifier } from '@trexolab/verifykit-core'
 
async function verifyDocument(pdfBytes: ArrayBuffer) {
  let verifier
  try {
    verifier = await createVerifier()
  } catch (err) {
    console.error('WASM initialization failed:', err)
    return
  }
 
  try {
    const result = await verifier.verify(pdfBytes, 'document.pdf')
 
    if (result.error) {
      // Partial failure: some signatures could not be parsed
      console.warn('Verification warning:', result.error)
    }
 
    return result
  } catch (err) {
    // Total failure: could not process the PDF at all
    const loadError = classifyPdfError(err)
    console.error(`${loadError.name}: ${loadError.message}`)
  } finally {
    verifier.dispose()
  }
}

Error Recovery Strategies

Invalid or Corrupt PDF

There is no recovery path for corrupt PDFs. Display an error message and prompt the user to provide a different file.

Password-Protected PDF

Catch PasswordException and prompt the user for the password. In the React viewer, this is handled automatically by the PasswordDialog component.

Network Failures

• AIA failures: Certificate chain validation will proceed with the certificates available in the PDF. The chain check may show unknown if intermediates are missing. Consider retrying or disabling AIA with enableAIA: false in air-gapped environments.
• Revocation failures: The revocation check will show unknown status. This does not affect the integrity or chain checks. Consider retrying or accepting the result without revocation data.

WASM Initialization Failure

• Check the browser console for CSP violations.
• Ensure the browser meets the minimum version requirements (see Browser Support).
• If using wasmUrl, verify the file is accessible and served with the correct MIME type.

Partial Verification Failure

When result.error is set but result.signatures is non-empty, the engine successfully verified some signatures but encountered issues with others. Display the available results and surface the error message for transparency.