Configuration

A tika-config.json is a single JSON object whose keys are the sections below. Every section is optional; anything you omit uses its defaults.

That list is exhaustive: an unrecognized top-level key is fatal at load time, and the error names the valid ones.

parsers, detectors, encoding-detectors, metadata-filters, content-handler-factory and parse-context are covered under Topics below. For server see Tika Server; for grpc see Tika gRPC; for pipes, fetchers, emitters, pipes-iterator, pipes-reporters and plugin-roots see Pipes Configuration.

Everything you configure is referenced by its component name — a kebab-case identifier such as pdf-parser, file-system-fetcher or unpack-config, derived from the class’s simple name unless the component declares its own. (developers/ calls the derived form a friendly name; it is the same string.) Class names are not accepted in their place: only components registered with @TikaComponent can be instantiated from JSON, which is what stops a config file from loading arbitrary classes. tika-app --list-parser-names prints the registered parser names, and an unknown name fails at load time listing the ones that are registered.

A parsers list loads only the parsers it names — every other parser is dropped. To customize one parser while keeping all the others, add a default-parser entry:

Configuring a parser automatically excludes its default copy, so there is no duplication. Omit default-parser only when you want a Tika limited to the parsers you listed.

detectors works the same way, with a default-detector entry. encoding-detectors has a default-encoding-detector, but it must not be mixed with explicit detector entries — see Encoding Detectors.

Text recognizers are engines that produce a document’s text from its pixels: an OCR engine run on an embedded image or a rendered PDF page, a VLM prompted to transcribe. A container parser invokes them on bytes it has already parsed. Two recipes cover almost every deployment.

Choose the engine. Configure it once under engines and name it here; every default parser stays loaded, and image-parser and pdf-parser call it:

An entry naming an engine takes only engine, _mime-include, _mime-exclude, min-width, min-height and checks; the engine’s own settings live under engines, where an inference binding can name the same engine. The 4.0 form, the engine inline, still works: { "tesseract-ocr-parser": { "language": "eng" } }, and takes the same keys. _mime-include/_mime-exclude keep their underscore because every component list uses the one spelling; min-width, min-height and checks belong to this list alone, so they need none, and the older _min-width/_min-height still mean the same (setting both spellings of one key fails the load). In the inline form these three are removed from the engine’s settings.

min-width/min-height keep an image whose recorded size (tiff:ImageWidth, tiff:ImageLength) falls short in either dimension away from the engine, in pixels; an image of unknown size is sent. Whatever the entry says, an image under 2 x 2 (a spacer in an email signature) never reaches any engine; the engines' own byte gates (minFileSizeToOcr) are unchanged.

Send the engine fewer images that hold no text. An entry’s checks lists image checks by name, run in order, cheapest first; the first to refuse keeps the image from the engine, whatever the engine is (Tesseract, a VLM, …​), and records skipped:<reason> in tk:ocr-warnings. For an inline image it is recorded on the parent document too, when the output is one metadata object per document (-J, /rmeta, Pipes). A check that cannot read the image admits it. The checks live in the tika-image-processing module (JDK only, no native code):

byte-size refuses an image shorter than minBytes or longer than maxBytes by its measured length, without reading it, so it belongs first; 0 turns a limit off, and an image whose length is unknown or only declared (by a container or a header) is admitted. min-image-size refuses an image under minTotalPixels in area or whose shorter side is under minShortSidePixels, by the dimensions in its header (it reads only the start of a large file, and the whole file only when the dimensions are not there); minWidthPixels and minHeightPixels ask for more of one dimension on top of minShortSidePixels, and 0 turns a test off. The min-image-size values shown are its defaults, and byte-size has no limit until set: below 100 x 100 an image holds a few characters at most, and a strip such as 11 x 1000 passes the area test but holds no line of text. blank-image-check refuses an image whose share of pixels differing from its most common gray level by more than tolerance is at most maxInk (0.0001 is 0.01 %, below a page with a line of text), measured on a copy of at most 1,000 pixels a side. With despeckle (on by default) a pixel counts only if most of its 3 x 3 neighbourhood differs from the background, so scattered specks, as on a noisy scan, do not hide a blank page: 0.1 % to 5 % salt-and-pepper noise comes out blank, and a stroke of text does not. An image with transparency is blank only if it is blank over both white and black, so dark or light text on a transparent background is kept. A progressive JPEG over 16 million pixels is not decoded (it is admitted): decoding one takes about 3 bytes of memory a pixel outside the Java heap.

A check’s settings need no underscore. min-width and min-height on the entry are a separate, metadata-only size minimum that runs before any check. The checks do not tell a photo from a page of text, and do not detect rotation. Nor do they, or the tk:ocr-warnings codes, catch fluent hallucinations (what they do not catch).

Turn OCR off. An empty list is authoritative:

Turn it off for one request. The list stays configured; the request switches it off, in every container, and no engine is missed as an error:

Engine types: tesseract-ocr-parser, tess4j-parser, openai-vlm-parser, claude-vlm-parser, gemini-vlm-parser. At startup Tika logs one line per engine with the media types it enriches, so the effective engine is never a guess.

A string value in the startup config may name an environment variable as ${env:NAME}, alone or inside a longer string, and the loader substitutes the variable’s value when the config is read:

Only that exact form is touched: ${NAME}, $NAME, ${sys:…​} and any other text stay literal, so a prompt or a pattern that happens to contain ${ is safe. A reference to a variable that is not set fails the load with the variable’s name and the JSON path, never a value, so a missing secret stops the server at startup rather than reaching a service as an empty key. A literal value works as before.

The forked parse workers of tika-server and Pipes never read the config file or the environment: the parent resolves every reference once and hands each fork the resolved config over its stdin, so a value that itself contains ${env:…​} is not expanded a second time. Presets written inline in the config file resolve at startup with the rest of it; catalog presets and per-request configuration (/config endpoints, pipes tuples) never do: a request cannot read the server’s environment.

A persistent config store (configStoreType file or Ignite) holds only fetchers and emitters registered at runtime (gRPC SaveFetcher), as the caller sent them. Components from the config file, with their resolved references, are never written to it.

JSON treats the backslash as an escape character, so path options (tesseractPath, imageMagickPath, …​) need forward slashes (C:/Tools/…​) or escaped backslashes (C:\\Tools\...). A single backslash is a JSON parse error.

To add components — extra EncodingDetector or Parser implementations, or their dependencies — without repackaging the application, drop their jars in a directory and point the tika.extras.dir system property at it:

Every *.jar in that directory joins the classpath Tika’s service loading scans, so SPI-registered components are picked up automatically. The jars are forwarded to the forked JVMs that Pipes and tika-server run, too, so they are present where parsing happens.

This is off by default: nothing is loaded unless tika.extras.dir is set, and there is no implicit default directory. Treat the directory as a trusted code location — anything in it runs with the full privileges of the Tika process, so it must not be writable by less-trusted principals, nor (on a server) reachable by request handling.

Parser configuration:

Other configuration: