FAQ
The questions below are the ones that come up most often when moving to 4.x. For pipes and tika-server runtime problems, see Pipes Troubleshooting. For anything not answered here, ask on user@tika.apache.org.
java -jar tika-app.jar fails with NoClassDefFoundError
The tika-app and tika-server-standard jars are thin launchers, not fat jars. Download the
matching .zip, unzip it into a directory (it has no top-level directory of its own), and run the
jar from inside that directory so that lib/ and plugins/ sit alongside it. See
the migration guide.
Why is my extracted content Markdown instead of XHTML?
Markdown is the default content handler in 4.x, in tika-app, tika-server, and the pipes
CLI alike. Ask for another format explicitly — tika-app -x, /tika/xml, --handler x — as described in
the migration guide.
My tika-config.xml no longer loads
4.x configuration is JSON. Convert an existing XML config with
java -jar tika-app.jar --convert-config-xml-to-json=tika-config.xml > tika-config.json,
then review the result — only the parsers section is converted. See
Configuration.
Where did resourceName and the X-TIKA:* keys go?
Every Tika-asserted key now lives under tk: in kebab-case (tk:resource-name,
tk:content, …). To keep an unmigrated consumer working, enable the
legacy-key-migration-filter, which rewrites keys at the emit edge in either direction. Both
the full rename table and the filter are documented in
Metadata Changes in 4.x.
tika-server returns 429 under load that used to succeed
/tika, /rmeta, /meta, and /unpack now parse in a fixed pool of numClients forked
JVMs instead of on the request thread, so a saturated pool pushes back rather than queueing.
The 429 is deliberate and distinguishable from a crashed fork’s 503 — see
Backpressure — and the
remedy is to size numClients for your request volume and core count
(Forked-JVM CPU and Heap Sizing).