Configuration

Without a file, Tika discovers everything through the Java ServiceLoader: every parser, detector and encoding detector on the classpath, with default options and no limits beyond the defaults. That is fine for a first program. A real intake service needs to decide:

In 4.x all of that lives in one JSON object. Two properties set it apart from the 3.x XML:

The startup file is trusted: it is written by the operator. Per-request configuration that arrives over the wire (a tika-server request body, a Pipes FetchEmitTuple) uses the same JSON shapes but is read in a restricted mode, never reads environment variables and is off by default in tika-server. That distinction matters for every security decision on this page.

Source: Apache Tika 4.1.x, Configuration and Apache Tika 4.1.x, Serialization and Configuration.

What happens, in order, verified in the 4.1.0 sources:

Source: the 4.1.0 sources of TikaJsonConfig, EnvInterpolator and TikaLoader.

A tika-config.json is a single JSON object. Every section is optional, and an omitted section uses its defaults. The table lists every key that the 4.1.0 loader accepts: this is the KNOWN_KEYS set in TikaJsonConfig, and the same list appears in the error message for an unknown key. The 4.1.x configuration page shows a skeleton that it calls exhaustive, but it leaves out three keys the 4.1.0 code accepts: engines, inference and presets.

Two notes on the table. First, service-loader is accepted and deserialized at load time, but in the 4.1.0 tika-serialization jar its config class (GlobalSettings.ServiceLoaderConfig) has no properties at all (checked with javap), so this page cannot tell you which option it takes; the 3.x attributes dynamic and loadErrorHandler have no documented 4.x equivalent. Second, TikaLoader itself does not read server, grpc, pipes, fetchers, emitters, pipes-iterator, pipes-reporters, plugin-roots or presets. It only accepts them, so one file can serve every process. Their own consumers validate them when they start, so a misspelled option inside pipes is reported by Pipes, not by TikaLoader.load.

Source: Apache Tika 4.1.x, Configuration, top-level JSON structure, KNOWN_KEYS in the 4.1.0 TikaJsonConfig source, Apache Tika 4.1.x, Tika Server (server fields and presets), Apache Tika 4.1.x, Tika gRPC and Apache Tika 4.1.x, Pipes Configuration.

Everything in the file is referenced by its component name: a kebab-case identifier such as pdf-parser, default-detector, output-limits or file-system-fetcher. The @TikaComponent annotation processor derives it from the class’s simple name (PDFParser becomes pdf-parser, ShelfCodeFilter becomes shelf-code-filter) unless the class declares its own name, and writes it into an index file such as META-INF/tika/parsers.idx. The loader looks names up in those index files. A class name is not accepted in its place: the failure message ends with "Arbitrary class names are not allowed for security reasons".

To list the names on your classpath, use tika-app:

Output (first lines of the parser list, tab-separated class and name):

With tika-parsers-standard-package 4.1.0 the parser list had 88 lines and the detector list 8. The derived names are not always the obvious ones (p-list-parser, bp-list-detector, poifs-container-detector), so copy them from this output instead of guessing. An unknown name also fails the load with the list of the registered ones, which is the other way to find a name. Names of components outside the parser and detector lists (parse-context entries, metadata filters, digesters) are in the .idx files inside each jar; for tika-core 4.1.0 the parse-context names are embedded-limits, exception-reporting, output-limits, timeout-limits, skip-embedded-document-selector, spooling-strategy, standard-metadata-limiter-factory, auto-detect-parser-config, simple-password-provider, text-recognizers, inference, media, pages, basic-content-handler-factory and sax-output-config.

Source: Apache Tika 4.1.x, Configuration, component names, Apache Tika 4.1.x, tika-app CLI and the META-INF/tika/parse-context.idx file of the tika-core 4.1.0 jar.

A parsers list loads only the parsers it names. To change one parser and keep all the others, add a default-parser entry. Configuring a parser automatically excludes its default copy, so a configured pdf-parser next to default-parser does not run twice.

exclude on default-parser takes component names and is only needed to disable a parser without replacing it. The Bookshelf upload form never accepts programs, so executable-parser is excluded.

To see what "only the parsers it names" means, the next run loads a file with just pdf-parser and parses both sample files. tk:parsed-by shows which parser ran.

The manuscript is still detected as a Word document (detection is a separate section), but no parser handles it, so EmptyParser returns no text and no error. Leaving out default-parser by accident is a silent loss of every other format; keep it unless you really want a Tika limited to the listed parsers.

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 encoding-detector entries. See Character Encoding Detection.

Source: Apache Tika 4.1.x, Configuration, the parsers list and default-parser and Apache Tika 4.1.x, Encoding Detectors.

The Bookshelf intake worker reads one file at startup. It keeps every default parser except the executable parser, orders PDF text by position, keeps four metadata fields, emits Markdown, and caps text, embedded depth and time.

The program builds the shared components once and a new ParseContext, Metadata and handler for each document.

Output (log lines on standard error omitted):

The startup log also has two INFO lines worth knowing: temporary files go to java.io.tmpdir=... (the loader’s temp directory check) and text recognizers: none found among the loaded parsers; images and rendered pages are not enriched, because Tesseract was not installed on the test machine. With Tesseract on the path, that second line names the engine and the media types it covers.

Source: composed for this page from Apache Tika 4.1.x, Configuration, Migrating to Tika 4.x, TikaConfig replaced by TikaLoader and TikaLoader, Javadoc 4.1.0.

org.apache.tika.config.loader.TikaLoader (module tika-serialization) replaces TikaConfig. Its public methods in 4.1.0, read from the jar with javap:

How to use it well:

Source: TikaLoader, Javadoc 4.1.0, Migrating to Tika 4.x, TikaConfig replaced by TikaLoader and the 4.1.0 TikaLoader source (caching, loadDefault, temp directory check).

The 4.x loader rejects unknown keys almost everywhere. Each configuration below was loaded with TikaLoader.load(path) followed by loadAutoDetectParser(), loadParseContext() and loadMetadataFilters(); the messages are the real 4.1.0 output, shortened where marked.

The 4.1.x documentation names four places that do not reject a typo, so a misspelling there has no effect and no error:

For the second case this page found the behaviour more nuanced than "no effect". A {"parse-context": {"pdf-parser": {"sortByPositon": true}}} passed every load call. The typo surfaced only when the PDF was parsed, as TikaException: TIKA-198: Illegal IOException from org.apache.tika.parser.pdf.PDFParser caused by the same Unrecognized field "sortByPositon", while the Word document parsed normally. So the mistake is not silent, but it appears per document, at parse time, and only for the formats that parser handles. Parse one sample of each important format in a startup or CI check after changing parse-context parser blocks.

Source: Apache Tika 4.1.x, Configuration, where a typo is caught, and where it is not; the experiments were run for this page against Tika 4.1.0.

Since 4.1.0 a string value in the startup file may reference an environment variable as ${env:NAME}, alone or inside a longer string. The loader substitutes the value when it reads the file. The exact pattern in the 4.1.0 EnvInterpolator source is \$\{env:([A-Za-z_][A-Za-z0-9_]*)}, so a variable name starts with a letter or an underscore and contains letters, digits and underscores.

The rules, checked against the source and with a run:

Run it with the variables set by the platform (a Kubernetes Secret, a systemd EnvironmentFile, the CI secret store), never with the values in a script:

TikaLoader.getConfig().getRootNode() returns the JSON after interpolation. Do not log it in production: it contains the resolved secrets.

Source: Apache Tika 4.1.x, Configuration, secrets from the environment, the 4.1.0 EnvInterpolator and TikaJsonConfig sources, and the Tika 4.1.0 release notes on the Apache Tika home page ("env-var interpolation in tika-config.json").

JSON treats the backslash as an escape character. Path options such as tesseractPath or imageMagickPath need forward slashes or doubled backslashes; a single backslash is a JSON parse error (the table above shows the message).

Forward slashes are the safer choice: they also survive being pasted into a shell, a YAML file or a Helm value. The Tesseract options themselves are on OCR with Tesseract; this example’s tesseractPath and tessdataPath names come from the 4.1.x Tesseract page and were not run on Windows for this page.

Source: Apache Tika 4.1.x, Configuration, Windows file paths.

To add components (an extra parser, encoding detector or their dependencies) to tika-app or tika-server without repackaging, put their jars in a directory and point the tika.extras.dir system property at it:

Every jar in that directory joins the classpath that Tika’s service loading scans, so SPI-registered components (and @TikaComponent names, through their .idx files) are picked up, and the jars are forwarded to the forked JVMs of Pipes and tika-server. The property is off by default and there is no implicit directory. In the Docker images, mount the directory at /tika-extras instead, which is already on the container classpath.

Treat that directory as trusted code: anything in it runs with the full privileges of the Tika process. It must not be writable by less-trusted users, nor reachable by request handling on a server. pf4j-managed Pipes plugins (plugins/, plugin-roots) are a separate mechanism, covered on the Tika Pipes page of this section.

In your own Java application you do not need tika.extras.dir: add the component as a normal dependency.

This page did not run tika.extras.dir; the description comes from the 4.1.x configuration and Docker pages.

Source: Apache Tika 4.1.x, Configuration, adding extra jars and Apache Tika 4.1.x, Docker.

Behind the JSON is the serialization system of tika-serialization, built on Jackson. The @TikaComponent annotation (org.apache.tika.annotation.TikaComponent, shipped in tika-core) is required for any class that should be configurable from JSON. At compile time the tika-annotation-processor reads it and:

The registry built from the index files is the security allow-list: only registered classes can be instantiated from JSON.

Three more ideas complete the model:

The restricted mode does not stop a request from configuring an already-loaded parser, because a parser’s config subtree is passed through unexamined. A request carrying {"parse-context": {"pages": {"text": "EXTRACT_AND_OCR"}}} reaches the PDF parser and takes effect. That is why tika-server gates per-request configuration separately with allowPerRequestConfig, off by default. Treat "callers may send per-request config" as "callers may set any parser option, including ones that start external processes such as OCR".

Source: Apache Tika 4.1.x, Serialization and Configuration, the 4.1.0 TikaComponent source and TikaComponent, Javadoc 4.1.0.

The same file is passed to every entry point.

Output of the tika-app line (the TikaCLI class run from the 4.1.0 tika-app jar with its dependencies on the classpath):

With a bad file tika-app stops before reading any document: Exception in thread "main" org.apache.tika.exception.TikaConfigException: Unknown configuration key(s): [parser]. Valid keys: [...]. In tika-app 4.1.0 --config is spelled --config=<file>; the batch mode also accepts -c <file>. A single .json argument with no other options is treated as an async (Pipes) configuration, not as a document.

tika-server requires a server section: in 4.1.0 a file without one makes the server refuse to start (TikaConfigException: Couldn't find 'server' element), and an empty "server": {} is enough. So the Bookshelf file above needs that one extra line before it is passed to tika-server or the Docker image. The server also reads the pipes and parse-context sections its forked parsing uses; tika-grpc reads its own grpc section in the same way. Those deployments are covered by the Tika Server (REST API), Docker & Kubernetes Deployment and Tika Pipes pages of this section; the commands above were not run for this page except the tika-app one.

Source: Apache Tika 4.1.x, tika-app CLI, Apache Tika 4.1.x, Tika Server, configuration, Apache Tika 4.1.x, Docker and the 4.1.0 TikaCLI source.

Tika 4.x does not read tika-config.xml at all, and TikaConfig is removed. Migration has three parts: convert the parsers section with the tool, migrate every other section by hand, and replace TikaConfig in code.

Source: Apache Tika 4.1.x, Setting limits and Apache Tika 4.1.x, Robustness.

The 3.x cells rest on the 3.3.2 configuration page and the 3.3.2 sources. The 1.x and 2.x cells that are filled in rest on the same sources and the book, and "not checked" means this page did not look at those releases. The AutoDetectParserConfig "since 2.1.1" note is from its Javadoc. Tika in Action predates JSON configuration entirely; its chapter 11 (extending Tika) registers custom parsers through META-INF/services, which @TikaComponent now generates for you.

Source: Migrating to Tika 4.x, Apache Tika 3.3.2, Configuring Tika and Tika in Action, chapter 11.