Packages

Pure Elixir utilities for PDF inspection, metadata, tokenizing, merging, page transforms, splitting, stamping, forms, attachments, outlines, text extraction, and native HTML/CSS and MathML rendering.

Current section

Files

Jump to
native_elixir_pdf_utilities docs diagnostics.md
Raw

docs/diagnostics.md

# Handling errors

PDF operations and HTML rendering return explainable failures as:

```elixir
{:error, {reason, diagnostic}}
```

Use `reason` to decide what your application does next. Use
`diagnostic.message` to explain or log the failure.

```elixir
require Logger

case NativeElixirPdfUtilities.Text.extract_file("report.pdf") do
  {:ok, text} ->
    text

  {:error, {reason, diagnostic}} ->
    Logger.warning("PDF operation failed: #{reason}: #{diagnostic.message}")
    {:error, reason}
end
```

## Understanding the diagnostic

| Field                       | Meaning                                 | Always present? |
| --------------------------- | --------------------------------------- | --------------- |
| `:reason`                 | The same reason atom as the outer tuple | Yes             |
| `:message`                | A description of the problem            | Yes             |
| `:stage`                  | Where processing stopped                | Yes             |
| `:operation`, `:module` | The operation and module reporting it   | No              |
| `:source`                 | A relevant path or input snippet        | No              |
| `:line`, `:column`      | A position in the source input          | No              |

Read optional fields with `Map.get/2`. Match reason atoms; message text may change.
Operation labels can differ from function names, such as `:stamp_text` or `:read`.

## Common failures

| Reason                                                       | What to check                                                            |
| ------------------------------------------------------------ | ------------------------------------------------------------------------ |
| `:invalid_options`                                         | Option names, types, and accepted values in the task guide               |
| `:invalid_html`, `:unsupported_html`, `:invalid_css`   | The source location and [supported HTML/CSS](html-to-pdf-compatibility.md) |
| `:invalid_pdf_input`                                       | Whether the input is a complete, readable PDF                            |
| `:encrypted_pdf`                                           | Supply an unencrypted PDF; decryption is not supported                   |
| `:unsupported_pdf_feature`, `:unsupported_text_encoding` | The relevant operation's supported inputs                                |
| `:resource_limit_exceeded`                                 | Document size/complexity and your [configured limits](resource-limits.md)  |

## Forms and attachments

Form and attachment operations use the same error tuple. Diagnostics identify
the module and operation. Field write errors include the field name in `:source`.

| Reason | Action |
| --- | --- |
| `:invalid_form` | Correct malformed or ambiguous field structures or HTML names. |
| `:unknown_form_field` | Inspect `Forms.fields/1` and use a returned name. |
| `:invalid_form_value` | Match the field type, declared choices and text constraints. |
| `:read_only_form_field` | Leave the read-only field unchanged. |
| `:unsupported_form` | Check the message for unsupported features, appearances or signed-document restrictions. |
| `:invalid_attachment` | Correct attachment metadata, duplicates or malformed embedded-file structures. |
| `:invalid_mime_type` | Correct conflicting type evidence or unsupported container metadata. |
| `:resource_limit_exceeded` | Reduce the workload or configure the named limit. |

Shared reader failures retain their original diagnostic stage and reason.
See [forms](pdf-forms.md) and [attachments](pdf-attachments.md) for supported
inputs and examples.

## API boundaries

### Application-facing operations

Use these modules for application work and untrusted input:

| Task | Modules |
| --- | --- |
| Render HTML | `HtmlToPdf` |
| Inspect PDFs | `Info`, `Text` |
| Edit PDFs | `Merge`, `Transform`, `Split`, `Stamp`, `Outlines`, `Forms`, `Attachments` |
| Check resource policy | `Limits.defaults/0`, `Limits.effective/0` |

Document operations validate their inputs. Ordinary file I/O failures also return
diagnostics. Successful processing does not mean a PDF is safe to open.

### Advanced building blocks

Pass each stage's output to the next. Avoid constructing intermediate maps yourself.
Documented stages and example fields share the 1.x compatibility promise.
Breaking changes require a new major version.

| Interface | Expected input and behavior |
| --- | --- |
| `Pdf.Reader` | Reads validated PDF objects and resolves references |
| HTML/CSS, style, layout, pagination, font and writer stages | Use validated output from the preceding stage |
| `PdfWriter.render/2` | Validates pages, drawings and font fields. Supply approved, parsed TrueType fonts; it does not decode font files |
| Writer font bounds | Metrics must fit TrueType integer fields. PDF permits at most 65,535 nonzero CIDs |
| `Tokenizer.new/1` | Takes a binary and returns state directly. Token-reading functions return lexical diagnostics |
| Font measurement/encoding helpers | Require valid inputs. Invalid constructor/helper arguments are programming errors |

For detailed errors, use:

| Stage | Function |
| --- | --- |
| HTML | `HtmlParser.parse_detailed/1` |
| CSS stylesheet | `CssParser.parse_detailed/1` |
| CSS declarations | `CssParser.parse_declarations_detailed/1` |
| Style | `Style.compute_detailed/2` |

Convenience parser and style functions return reason atoms. `Layout.layout/2`
does too. `HtmlToPdf.render/2` converts pipeline failures to diagnostics.

### Internal modules

`@moduledoc false` modules and `@doc false` functions are internal. Their maps
can change. Use public APIs instead of calling internal writers, caches or
validator preparation code with unchecked data.

## Image failures

| Source | Diagnostic details |
| --- | --- |
| `"PNG"` | Palette, CRC, scanline or compressed-data failures |
| `"SVG"` | XML line number when available; converter errors keep their message |

| Reason | Next step |
| --- | --- |
| `:invalid_document` | Re-export the image or remove unsupported SVG features |
| `:resource_limit_exceeded` | Reduce image size/complexity or review the named limit |

Do not automatically retry with higher limits. See [image requirements](image-processing.md).