# Error handling and logging

Source: https://sdk.pdf.net/docs/v1/guides/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 [#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 [#error-classes]

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

| Class                    | Thrown when                                                             |
| ------------------------ | ----------------------------------------------------------------------- |
| `DocumentNotLoadedError` | An operation requires a document, and none is loaded.                   |
| `InvalidInputError`      | The input passed to the API is invalid.                                 |
| `InvalidPasswordError`   | The document is encrypted, and the password is missing or wrong.        |
| `DocumentFormatError`    | The PDF content is malformed beyond what the SDK can work around.       |
| `NotSupportedError`      | The document uses a PDF feature the SDK doesn't support yet.            |
| `UninitializedError`     | An object is used before its asynchronous initialization has completed. |

Catch and narrow with `instanceof`, as the password flow in [Getting started](https://sdk.pdf.net/docs/v1/guides/getting-started) does.

## Log messages [#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:

```tsx
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).