This page is an in-progress attempt to document best practice for Parser authors on how to handle problematic files

Allowed Responses

The Parser contract is that a Tika parser will populate the Metadata object, send XML events to the ContentHandler, or throw one of:

Suggested Responses

Corrupt File

If the file is corrupted in some way, and cannot be processed, a CorruptedFileException (subclass of TikaException) should be thrown (see Parser contract)

File cannot be read

If an IO problem occurs when reading the document, an IOException should be thrown (see Parser contract)

The only exception is if an underlying library throws an IOException to indicate a broken / corrupted file, in which case catching the IOException and re-throwing a CorruptedFileException may be done by the parser to give a more helpful error.

"Empty" File (No Text)

If there is no text in the file, either because it's empty (eg 0 byte text file), or because it's a format that doesn't have text (eg an image), then ???

TBC - should the body be opened then immediately closed, or something else?

File is password protected

EncryptedDocumentException (a subtype of TikaException) should be thrown if the file is password protected and no/incorrect password is given.

(A PasswordProvider should be placed on the ParseContext if known, to allow the parsing to proceed without error)

File would require too much memory to process

Where the file format permits predicting the amount of memory required to process it (eg a length field near the start of a block that must be fully processed to proceed), and the parser knows this is more than available / permitted, a TikaMemoryLimitException should be thrown to abort the processing.

If it isn't possible to detect this in advance, parsers should try to abort with a TikaMemoryLimitException when they spot things going wrong.

Otherwise, there's a reason we suggest using a separate JVM via ForkParser or TikaServer or similar....

Parser can't handle File

If the file is in a sub-format that the parser can't handle (eg parser supports v2 and v3, document is v1, all share the same mimetype), or uses some options that means that parser can't sensibly handle it, then a UnsupportedFormatException should be thrown

Where possible though, the mimetype and/or detection should be updated to prevent an unsupported version of the file format ending up with the parser!

Document Structure is Broken

If something is very broken with the file / file structure, and it will be impossible to output valid XML for it for some reason, then probably a SAXException is the right thing

Document requests no extraction

Some file formats allow extraction, but request politely that it not be done. Depending on your Tika use case (eg forensics vs user facing search), you may wish to abort processing, or you may wish to process + pass the permission details up the chain.

To pass but inform the caller of the access restrictions, populate the https://tika.apache.org/1.19/api/org/apache/tika/metadata/AccessPermissions.html AccessPermissions metadata properties

To abort, eg if the caller requested strict permissions enforcements, throw a AccessPermissionException

Tika-only Responses

These Exceptions should only be thrown by the core of Tika itself, not the underlying parsers

Broken Tika Config

If the user specifies some configuration for Tika, either explicitly or implicitly (eg extension resources with the right magic specific name on the classpath), and the config supplied is invalid and can't be worked around, a TikaConfigException will be thrown during the initialisation of Tika

Zero byte length file

Tika can provide a suggested mime type for these, but not extract any content. Caused typically by Right Click -> New or touch, or an error in getting the file to where it is now.

If passed one of these for detection, no error should be given, and a filename-only answer supplied

If passed one of these for parsing, a ZeroByteFileException should be thrown

ErrorsAndExceptions (last edited 2018-11-08 23:35:30 by NickBurch)