Migrating Tika Server to 4.x

POST endpoints accept multipart requests with a file part and optional config part:

In 3.x, error responses from /tika, /rmeta, and /unpack returned a plain-text body such as "Parse failed: TIMEOUT". In 4.x these endpoints return a JSON body with at least a status field:

A message field is included when one is available and may contain a server-side stack trace, e.g. {"status": "TIMEOUT", "message": "Task timed out after 60000ms"}.

The HTTP status codes are also more precise:

The raw /tika, /tika/text, /tika/html, /tika/xml, and /tika/md endpoints return 422 with the extracted content as the body when a container-level exception occurs during a partial parse; the exception itself is not appended to the raw body — use /rmeta for the structured exception.

Migration: Clients that parse plain-text error bodies must switch to JSON. Clients that branch only on HTTP status code should account for the 429/400/413 mappings above and stop treating UNSPECIFIED_CRASH as 500.

/pipes response body. /pipes now returns the same JSON body as /tika, /rmeta, and /unpack — {"status":"<RESULT_STATUS>","message":"…​"} — where status is the PipesResult status enum (EMIT_SUCCESS, EMIT_SUCCESS_PARSE_EXCEPTION, PARSE_EXCEPTION_NO_EMIT, TIMEOUT, OOM, FETCHER_NOT_FOUND, …​) and message carries the exception when there is one. It previously used a /pipes-only shape ({"status":"ok"|"process_crash"|"application_error", …​} with type, parse_exception, and a stringified emitted). A parse that threw is now reported by its status enum, not as "ok".

/pipes also rejects with 400: a malformed request body (the reason is in the response), and any emit strategy other than EMIT_ALL — the /pipes response carries only status and message, so a passback strategy would silently discard the parsed data. Use /rmeta if you want the data passed back.

/async request body. POST /async now requires an object envelope, {"tuples":[ …​ ]}, instead of a bare JSON array; the envelope leaves room for future batch-level fields. A bare array (or any body without a tuples array) is rejected with 400, as is a tuple naming a fetcher or emitter the server does not have — validated at POST time, before anything is queued. A batch larger than the queue’s total capacity is also a 400 telling the caller to split it: retrying cannot help. 429 with Retry-After is reserved for transient fullness, where the same batch can succeed later.

FetchEmitTuple wire format. The per-tuple parse-context key is parse-context; 3.x used parseContext. An unknown field anywhere in a tuple is rejected with a 400 naming the field and listing the known ones, instead of being silently ignored.

/meta previously parsed in-process, in the request-handling JVM, with no crash isolation and its own ad hoc error handling (500 for most parse failures, 400 for a field that couldn’t be extracted from an incompletely-parsed document). It now shares the same pipes-backed PipesParser as /tika, /rmeta, and /unpack (see Endpoints and Forked-Process Groups), with the same crash isolation and the same per-document exception handling as those endpoints (see Error Responses):

Migration: clients that treated any non-200 from /meta as "parse failed" should check the new status codes above. Clients that inspected the response body for error text should check tk:exception:container-exception (full-object endpoints) or the 422 body (/meta/{field}).

The default representation is now JSON, not CSV. A /meta request without an Accept header returned CSV in 3.x; it now returns JSON. CSV is still available with Accept: text/csv.

Two changes to the returned metadata come with this, neither of which produces an error:

The /tika endpoint no longer routes on the Accept header. Name the format in the path instead — /tika/text, /tika/html, /tika/json, and the rest of the table above.

This replaces the enableUnsecureFeatures flag that alpha-1 briefly used, and before that, enabling these capabilities simply by listing endpoints under server.endpoints. enableUnsecureFeatures no longer exists: a config that still carries it fails to start with an "Unrecognized field" error naming the key, rather than silently ignoring it. The single flag has been split into two, so that granting batch/fetcher access and granting per-request parser configuration are separate decisions:

The capabilities are two default-false flags in the server section:

/status is no longer gated: it exposes only aggregate counters, so it is enabled simply by listing status under endpoints.

The endpoints allowlist now also gates SPI-provided resources: a discovered resource whose root path matches a named endpoint binds only when that endpoint is enabled (e.g. the application/rdf+xml XMP resource serves /meta, so omitting meta removes it too). An SPI resource with a custom root path still loads unconditionally — installing the jar is the opt-in.

Migration: if your config selects pipes or async, add "allowPipes": true; if you rely on per-request config, add "allowPerRequestConfig": true:

The following TikaServerConfig options have been removed:

4.x configures parsing through the tika-config file, not through request headers. The remaining per-request configuration headers have been removed and are now silently ignored if sent — the request succeeds, the header has no effect:

The X-Tika-OCR* and X-Tika-PDF* header families were removed earlier in the 4.x line. Parser configuration is now supplied as JSON.

Migration: move these settings into your tika-config. For per-request values, POST to a /config endpoint (/tika/config, /tika/config/json, /rmeta/config, /meta/config) with the JSON above as the multipart config part; this requires allowPerRequestConfig=true.

Transport headers are unaffected: Content-Disposition, Content-Type and Content-Length still describe the payload and still influence detection.

No pipes or fetcher configuration is required to start the server: the default-on endpoints (/tika, /rmeta, /meta, /unpack, /detect) run on the built-in \_\_bytes fetcher for content carried inside the request, an internally-configured spool fetcher for anything larger, and a default pipes config, and the server starts with no config file at all. You need a pipes section and your own file-system-fetcher only when you enable allowPipes and want /pipes//async to fetch documents from a directory you control:

The 3.x pipes keys staleFetcherTimeoutSeconds and staleFetcherDelaySeconds are gone. A pipes config still carrying either fails startup: unknown pipes keys are rejected, not ignored.

The request-body cap was unlimited by default in the prereleases; it now defaults to 1 GiB. Bodies above maxInlineBytes are spooled to disk, so this also bounds how much one request can write, and a body over the limit is rejected with 413.

Migration: if you legitimately post bodies larger than 1 GiB, set "maxRequestSizeBytes" in the server section above your largest payload (or -1 to restore no limit).

The http-fetcher now verifies TLS certificates by default (verifySsl defaults to true). A pipeline that fetched from a self-signed or internal host and previously succeeded will start failing at the TLS handshake.

Migration: trust the host’s CA (preferred), or set verifySsl: false on the fetcher if you accept the risk.

All parsing now occurs in isolated child processes, providing:

This isolation carries a throughput and memory cost relative to a single in-JVM parser, and the size of that cost depends on your document mix and the pool configuration (per-client versus shared-server, numClients, per-fork heap). See Performance and Isolation Trade-offs for the comparison and tuning guidance.

In 3.x a saturated server had no way to say so. /tika, /rmeta, and /unpack parsed in the request-handling JVM, so load simply piled onto request threads, and a client could not tell overload apart from a document that broke the parse.

Because parsing now runs in a fixed pool of forks, 4.x reports the two conditions differently:

A client, load balancer, or queue consumer can now back off on the first, quarantine or route elsewhere on the second, and drop the third — instead of hammering a busy server or failing blind on a single opaque status.

The cost is a sizing decision 3.x did not ask of you: the pool is exactly numClients forks wide. 429 under normal load is what "too small for this request volume" looks like; forks starving each other of CPU is what "too large for this host" looks like. Neither raises an error naming numClients, so size it deliberately — see Forked-JVM CPU and Heap Sizing.