Handling errors

View Source

PDF operations and HTML rendering return explainable failures as:

{:error, {reason, diagnostic}}

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

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

FieldMeaningAlways present?
:reasonThe same reason atom as the outer tupleYes
:messageA description of the problemYes
:stageWhere processing stoppedYes
:operation, :moduleThe operation and module reporting itNo
:sourceA relevant path or input snippetNo
:line, :columnA position in the source inputNo

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

ReasonWhat to check
:invalid_optionsOption names, types, and accepted values in the task guide
:invalid_html, :unsupported_html, :invalid_cssThe source location and supported HTML/CSS
:invalid_pdf_inputWhether the input is a complete, readable PDF
:encrypted_pdfSupply an unencrypted PDF; decryption is not supported
:unsupported_pdf_feature, :unsupported_text_encodingThe relevant operation's supported inputs
:resource_limit_exceededDocument size/complexity and your configured limits

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.

ReasonAction
:invalid_formCorrect malformed or ambiguous field structures or HTML names.
:unknown_form_fieldInspect Forms.fields/1 and use a returned name.
:invalid_form_valueMatch the field type, declared choices and text constraints.
:read_only_form_fieldLeave the read-only field unchanged.
:unsupported_formCheck the message for unsupported features, appearances or signed-document restrictions.
:invalid_attachmentCorrect attachment metadata, duplicates or malformed embedded-file structures.
:invalid_mime_typeCorrect conflicting type evidence or unsupported container metadata.
:resource_limit_exceededReduce the workload or configure the named limit.

Shared reader failures retain their original diagnostic stage and reason. See forms and attachments for supported inputs and examples.

API boundaries

Application-facing operations

Use these modules for application work and untrusted input:

TaskModules
Render HTMLHtmlToPdf
Inspect PDFsInfo, Text
Edit PDFsMerge, Transform, Split, Stamp, Outlines, Forms, Attachments
Check resource policyLimits.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.

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

For detailed errors, use:

StageFunction
HTMLHtmlParser.parse_detailed/1
CSS stylesheetCssParser.parse_detailed/1
CSS declarationsCssParser.parse_declarations_detailed/1
StyleStyle.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

SourceDiagnostic details
"PNG"Palette, CRC, scanline or compressed-data failures
"SVG"XML line number when available; converter errors keep their message
ReasonNext step
:invalid_documentRe-export the image or remove unsupported SVG features
:resource_limit_exceededReduce image size/complexity or review the named limit

Do not automatically retry with higher limits. See image requirements.