Error handling and logging

The SDK reports problems through two channels. When an operation is impossible, fully or partially, it throws a typed error and changes nothing. When it hits a problem it can work around, such as a malformed document or an unsupported PDF feature, it completes the operation and emits a log message instead. Log messages are never printed to the browser console by the SDK: subscribe to receive them.

When the SDK throws

• Functions that modify the document validate their input first and throw before touching anything, so the document is never left half-changed: DocumentNotLoadedError when no document is loaded, InvalidInputError when the input is invalid.
• Functions that only read (getters, subscriptions) don't throw and don't log: with no document loaded or an invalid input, they return empty values.
• Hooks never throw during render. A hook that returns an imperative function validates when that function is called.

Error classes

Every SDK error extends GenericError (itself extending Error) and carries a static message plus an optional data object with the variable details:

Catch and narrow with instanceof, as the password flow in Getting started does.

Log messages

logMessages delivers everything the SDK logs; subscribing returns an unsubscribe function. Each message carries a level, a reason, a static message string, and the variable details in data. Because the message strings are static, messages group cleanly in log aggregation:

import { logMessages, LogLevel } from '@sdk-pdf/react'

const unsubscribe = logMessages.on('message', (logMessage) => {
  // The numeric levels order by severity, so a threshold is a single comparison.
  if (logMessage.level >= LogLevel.Warning) {
    reportToMonitoring(logMessage.message, logMessage.data)
  }
})

The levels are Debug, Info, Warning, and Error. The reason tells what kind of problem was hit: a document format issue, an unsupported feature, a performance issue, invalid input, an unexpected error, or a notice from the license server such as an exceeded usage quota (LogReason lists them).