pdftract/docs/integrations/diagnostics-codes.md

pdftract Diagnostic Codes

This document catalogs all diagnostic codes emitted by pdftract during PDF extraction. Each diagnostic has a stable SCREAMING_SNAKE_CASE identifier, a severity level, and suggested user action.

Diagnostic Format

All diagnostics follow this structure:

{
  "code": "DIAGNOSTIC_CODE",
  "message": "Human-readable description",
  "severity": "info|warning|error|fatal",
  "page_index": null | 0-based page number,
  "location": null | {"object_number": N, "generation_number": G},
  "hint": null | "Suggested action"
}

Code Categories

STRUCT_* — PDF Structure Errors

Errors related to PDF syntax, object parsing, and document structure.

Code	Severity	Description	Phase
STRUCT_INVALID_NAME	Warning	Invalid name character or malformed name object	1.1
STRUCT_INVALID_HEX	Warning	Invalid hex character in hex string or name escape	1.1
STRUCT_INVALID_OCTAL	Warning	Invalid octal escape sequence in literal string	1.1
STRUCT_INVALID_STREAM_HEADER	Warning	Invalid stream header (stream keyword not followed by proper newline)	1.1
STRUCT_UNEXPECTED_BYTE	Warning	Unexpected byte (e.g., stray > not part of >>)	1.1
STRUCT_UNEXPECTED_EOF	Warning	Unexpected end of file while parsing a token	1.1
STRUCT_UNTERMINATED_STRING	Warning	Unterminated literal string (missing closing paren)	1.1
STRUCT_MISSING_KEY	Warning	Missing required dictionary key	1.4
STRUCT_CIRCULAR_REF	Warning	Circular reference detected (A → B → A)	1.2
STRUCT_XOBJECT_CYCLE	Warning	Form XObject cycle detected	3.3
STRUCT_DEPTH_EXCEEDED	Warning	Dictionary nesting depth exceeds limit	1.2
STRUCT_INVALID_DICT_VALUE	Warning	Invalid dictionary value (missing value after key)	1.2
STRUCT_INVALID_DICT_KEY	Warning	Invalid dictionary key (not a name object)	1.2
STRUCT_INVALID_INDIRECT_HEADER	Warning	Invalid indirect object header (N G obj)	1.2
STRUCT_INTEGER_OVERFLOW	Warning	Integer overflow during parsing	1.2
STRUCT_REAL_INVALID	Warning	Invalid real number literal	1.1
STRUCT_INVALID_NUMBER	Warning	Invalid numeric literal	1.1
STRUCT_INVALID_ASCII85	Warning	Invalid ASCII85 character or malformed stream	1.5
STRUCT_INVALID_OBJSTM	Warning	Invalid object stream format	1.2
STRUCT_INVALID_GEOMETRY	Warning	Invalid geometry value (NaN or Inf in MediaBox/CropBox/Rotate)	1.7
STRUCT_INVALID_TYPE	Warning	Invalid object type (expected type not found)	5.2.1
STRUCT_INVALID_UTF16	Warning	Invalid UTF-16BE encoding in string	1.4
STRUCT_UNRESOLVED_DESTINATION	Warning	Unresolved named destination	1.4
STRUCT_NON_GOTO_OUTLINE	Warning	Non-GoTo action in outline	1.4
STRUCT_INVALID_PDFDOC_ENCODING	Warning	Invalid PDFDocEncoding in string	1.4
STRUCT_HYBRID_CONFLICT	Warning	Hybrid xref conflict: traditional and stream disagree	1.3
STRUCT_INCOMPLETE_COVERAGE	Info	StructTree coverage below 80% with /Suspects true	7.1.4
STRUCT_INVALID_PREV_OFFSET	Warning	Invalid /Prev offset in xref chain	1.3
STRUCT_INVALID_BDC_OPERAND	Info	Invalid BDC operand	3.4

XREF_* — Cross-Reference Table Errors

Errors related to the xref table and trailer.

Code	Severity	Description	Phase
XREF_INVALID_HEADER	Warning	Invalid xref keyword or header	1.3
XREF_INVALID_ENTRY	Warning	Malformed xref entry (not 20 bytes, bad format)	1.3
XREF_INVALID_SUBSECTION_HEADER	Warning	Invalid subsection header (not "start count")	1.3
XREF_OBJECT_ZERO_NOT_FREE	Warning	Object 0 is not free (violates PDF spec)	1.3
XREF_TRAILER_NOT_FOUND	Warning	Trailer dictionary not found or malformed	1.3
XREF_TRUNCATED	Warning	Truncated xref table (unexpected EOF)	1.3
XREF_REPAIRED	Info	Xref was reconstructed via forward scan (EC-07)	1.3
XREF_LINEARIZED_NO_FORWARD_SCAN	Warning	Forward scan disabled for linearized files	1.3
XREF_REMOTE_NO_FORWARD_SCAN	Warning	Forward scan disabled for HTTP sources	1.3
XREF_INVALID_STREAM_FORMAT	Warning	Invalid xref stream format	1.3
XREF_INVALID_STREAM_ENTRY	Warning	Invalid xref stream entry	1.3

STREAM_* — Stream Decoder Errors

Errors related to stream decompression and filters.

Code	Severity	Description	Phase
STREAM_DECODE_ERROR	Warning	Stream decompression failed (corrupt data)	1.5
STREAM_BOMB	Error	Decompression bomb limit exceeded	1.5
STREAM_UNKNOWN_FILTER	Warning	Unknown filter name	1.5
STREAM_INVALID_PARAMS	Warning	Invalid filter parameters	1.5
STREAM_INVALID_JPEG	Warning	JPEG data has invalid or missing markers	1.5
STREAM_INVALID_CCITT	Warning	CCITT fax data has invalid or missing parameters	1.5
STREAM_TRUNCATED	Warning	Stream data truncated	1.5 / 5.2.1

ENCRYPTION_* — Encryption Errors

Errors related to PDF encryption and passwords.

Code	Severity	Description	Phase
ENCRYPTION_UNSUPPORTED	Fatal	Unsupported encryption or no password supplied	1.4
ENCRYPTION_WRONG_PASSWORD	Fatal	Password incorrect	1.4

PAGE_* — Page-Level Errors

Errors related to page structure and properties.

Code	Severity	Description	Phase
PAGE_OUT_OF_RANGE	Error	Page number out of range	1.8
PAGE_INVALID_COUNT	Warning	Invalid /Count in /Pages tree	1.4
PAGE_INVALID_ROTATE	Warning	Invalid /Rotate value (not multiple of 90)	1.4

FONT_* — Font Pipeline Errors

Errors related to font parsing and glyph mapping.

Code	Severity	Description	Phase
FONT_GLYPH_UNMAPPED	Warning	Glyph could not be mapped to Unicode	2.2
FONT_NOT_FOUND	Warning	Font not found or couldn't be parsed	2.1
FONT_INVALID_CMAP	Warning	Invalid CMap format	2.2
FONT_PARSE_FAILED	Warning	Font program parsing failed	2.1
FONT_UNSUPPORTED	Warning	Font type not supported for embedded loading	2.1
FONT_CIDTOGIDMAP_TRUNCATED	Warning	CIDToGIDMap stream has odd byte count	2.1
ENCODING_DIFFERENCE_OUT_OF_RANGE	Warning	Character code in /Differences exceeds valid range	2.2
FONT_TYPE3_WIDTHS_LENGTH_MISMATCH	Warning	Type3 font /Widths array length mismatch	2.4

CJK_* — CJK Encoding Errors

Errors related to CJK character encoding.

Code	Severity	Description	Phase
CJK_DECODE_MALFORMED	Warning	Malformed byte sequence in CJK encoding	2.3

OCR_* — OCR Pipeline Errors

Errors related to OCR processing.

Code	Severity	Description	Phase
OCR_JBIG2_UNSUPPORTED	Warning	JBIG2 decoder not available	1.5 / 5.2
OCR_JPX_UNSUPPORTED	Warning	JPEG2000 (JPX) decoder not available	1.5 / 5.2
OCR_CCITT_UNSUPPORTED	Warning	CCITT fax decoder not available	1.5 / 5.2
OCR_TESSERACT_FAILED	Warning	Tesseract OCR failed	5.4
OCR_BROKENVECTOR_UNAVAILABLE	Warning	OCR unavailable on broken-vector page	4.7
OCR_LANGUAGE_UNAVAILABLE	Warning	Requested OCR language pack not available	5.4

IMG_* — Image Processing Errors

Errors related to image extraction and processing.

Code	Severity	Description	Phase
IMG_SOFTMASK_UNSUPPORTED	Warning	Image soft mask not supported in direct compositing	5.2.1
IMG_UNSUPPORTED_FORMAT	Warning	Image format not supported	5.2.1
IMG_DESKEW_OUT_OF_RANGE	Warning	Deskew angle out of detectable range	5.3.1
IMG_SOURCE_MIXED	Warning	Image sources mixed in unexpected way	5.3.2

REMOTE_* — Remote Source Errors

Errors related to HTTP fetching and remote sources.

Code	Severity	Description	Phase
REMOTE_FETCH_INTERRUPTED	Error	HTTP fetch interrupted or failed	1.8
REMOTE_NO_RANGE_SUPPORT	Warning	Server does not support Range requests	1.8
REMOTE_TLS_FAILED	Fatal	TLS handshake failed	1.8
REMOTE_DNS_FAILED	Fatal	DNS resolution failed	1.8
REMOTE_URL_PRIVATE_NETWORK	Error	URL targets private network (SSRF protection)	1.8

GSTATE_* — Graphics State Errors

Errors related to graphics state operators.

Code	Severity	Description	Phase
GSTATE_STACK_OVERFLOW	Warning	Graphics state stack overflow	3.1
GSTATE_STACK_UNDERFLOW	Warning	Graphics state stack underflow	3.1
GSTATE_BT_ET_MISMATCH	Warning	Mismatched BT/ET pair	3.1
CM_ARG_COUNT	Warning	Invalid argument count for cm operator	3.1
CM_DEGENERATE	Warning	Degenerate matrix (det == 0 or NaN)	3.1
HORIZ_SCALING_ZERO	Warning	Horizontal scaling set to zero (Tz 0)	3.1
TEXT_RENDERING_MODE_CLAMPED	Warning	Text rendering mode clamped to valid range	3.1
TSTAR_ZERO_LEADING	Warning	T* operator when leading == 0	3.1
FONT_RESOURCE_NOT_FOUND	Warning	Font resource not found	3.1
FONT_SIZE_ZERO_OR_NEGATIVE	Warning	Font size zero or negative	3.1
BT_NESTED	Warning	BT operator nested inside another BT block	3.1
ET_WITHOUT_BT	Warning	ET operator without matching BT	3.1
TEXT_SHOW_OUTSIDE_BT	Warning	Text-show operator outside BT/ET block	3.1

LAYOUT_* — Layout and Reading Order Errors

Errors related to layout analysis and reading order.

Code	Severity	Description	Phase
TAGGED_PDF_STRUCT_TREE_DEFERRED	Info	Tagged PDF StructTree deferred to Phase 7	4.5
LAYOUT_READING_ORDER_AMBIGUOUS	Warning	Reading order may be incorrect	4.5
LAYOUT_LOW_READABILITY	Warning	Low readability score	4.7

MCP_* — MCP Server Errors

Errors related to MCP server operations.

Code	Severity	Description	Phase
MCP_TOOL_INVALID_PARAMS	Error	MCP tool call has invalid parameters	6.7
MCP_PATH_TRAVERSAL	Error	MCP path traversal attempt	6.7

CACHE_* — Cache Errors

Errors related to caching operations.

Code	Severity	Description	Phase
CACHE_ENTRY_CORRUPT	Warning	Cache entry is corrupted	6.9
CACHE_WRITE_FAILED	Warning	Cache write failed	6.9

MARKED_CONTENT_* — Marked Content Errors

Errors related to marked content operators.

Code	Severity	Description	Phase
EMC_WITHOUT_BMC	Info	EMC operator without matching BMC/BDC	3.4
MARKED_CONTENT_DEPTH_EXCEEDED	Info	Marked-content stack depth exceeded	3.4
UNKNOWN_MARKED_CONTENT_PROPS	Info	Unknown marked-content property name	3.4
MCID_REDEFINED	Info	MCID redefined in same scope	3.4

PROFILE_* — Profile Errors

Errors related to profile configuration.

Code	Severity	Description	Phase
PROFILE_SECRETS_FORBIDDEN	Error	Profile YAML contains forbidden secret keys	7.10
PROFILE_INVALID	Error	Profile YAML is invalid or malformed	5.6.2

REPAIR_* — Repair Recovery

Errors related to document repair operations.

Code	Severity	Description	Phase
REPAIR_RESCUED_FROM_BACKWARDS_XREF	Info	Xref repaired from backwards scan	1.3

SECURITY_* — Security Diagnostics

Security-related diagnostics.

Code	Severity	Description	Phase
JAVASCRIPT_PRESENT	Info	JavaScript present in PDF (never executed)	1.2

Adding New Diagnostic Codes

When adding a new diagnostic code:

1. Choose a category prefix (STRUCT, STREAM, XREF, etc.)
2. Add the variant to the DiagCode enum in crates/pdftract-core/src/diagnostics.rs
3. Add the name mapping in DiagCode::name()
4. Add the category mapping in DiagCode::category()
5. Add the severity mapping in DiagCode::severity()
6. Add a catalog entry to DIAGNOSTIC_CATALOG
7. Add an entry to this document

Code naming convention: CATEGORY_SPECIFIC_ISSUE (SCREAMING_SNAKE_CASE)

Severity levels:

• Info — does not affect output validity
• Warning — output is usable but degraded
• Error — output for this region/page is invalid; other regions OK
• Fatal — extraction aborted, no usable output

Programmatic Usage

Diagnostics can be consumed programmatically:

import json

result = json.loads(pdftract_output)
for error in result.get('errors', []):
    code = error['code']
    severity = error['severity']
    page = error.get('page_index')
    
    if code == 'OCR_BROKENVECTOR_UNAVAILABLE':
        # Install Tesseract for OCR recovery
        print(f"Page {page}: Install Tesseract for OCR recovery")