TIKA-4753 - improve oom/timeout/crash msg (#2870)

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Author: tballison

docs/modules/ROOT/pages/migration-to-4x/migrating-tika-server-4x.adoc

@@ -89,6 +89,29 @@ The separate `/config` endpoints have been removed. Configuration is now handled
 
 **Migration:** Use `POST /tika` or `POST /tika/json` with a `config` part in your multipart request.
 
+=== Error Response Bodies Are Now JSON
+
+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:
+
+[source,json]
+----
+{"status": "TIMEOUT"}
+----
+
+When the server is configured with `returnStackTrace=true`, a `message` field is also
+included (it 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:
+
+* `UNSPECIFIED_CRASH` changed from `500` to `503` — it is a transient process failure
+  in the same category as `TIMEOUT` and `OOM`, not a server misconfiguration.
+
+**Migration:** Clients that parse plain-text error bodies must switch to JSON. Clients
+that branch only on HTTP status code are unaffected unless they were treating
+`UNSPECIFIED_CRASH` as a `500`.
+
 === Accept Header Routing Removed
 
 The `/tika` endpoint no longer routes based on `Accept` headers. Use explicit paths instead:

docs/modules/ROOT/pages/using-tika/server/index.adoc

@@ -156,6 +156,45 @@ curl -T document.pdf http://localhost:9998/meta/Content-Type   # single field
 * `/translate/all/\{translator}/\{src}/\{dest}` — translation
 * `/pipes`, `/async` — Pipes-based bulk processing
 
+== Error Responses
+
+When parsing fails due to a process-level problem — the forked child process timed out,
+ran out of memory, or crashed unexpectedly — the server returns an HTTP error with a
+JSON body whose shape matches the `PipesResult` status:
+
+[source,json]
+----
+{"status": "TIMEOUT"}
+----
+
+The `status` field is the `PipesResult.RESULT_STATUS` enum name. By default the body
+carries only the `status`. When the server is configured with `returnStackTrace=true`,
+a `message` field is also included (it often contains a server-side stack trace), e.g.
+`{"status": "TIMEOUT", "message": "Task timed out after 60000ms"}`.
+
+[cols="1,1,3"]
+|===
+|HTTP status |`status` values |Meaning
+
+|`503 Service Unavailable`
+|`TIMEOUT`, `OOM`, `UNSPECIFIED_CRASH`, `CLIENT_UNAVAILABLE_WITHIN_MS`
+|The forked parse process failed, or no parse client became available within the
+configured wait time (`CLIENT_UNAVAILABLE_WITHIN_MS`). The server is still healthy;
+the client may retry.
+
+|`500 Internal Server Error`
+|`FAILED_TO_INITIALIZE`, `FETCH_EXCEPTION`, `EMIT_EXCEPTION`,
+`FETCHER_NOT_FOUND`, `EMITTER_NOT_FOUND`,
+`FETCHER_INITIALIZATION_EXCEPTION`, `EMITTER_INITIALIZATION_EXCEPTION`
+|Server misconfiguration or a task-level infrastructure error. Retrying the same
+document on the same server is unlikely to succeed without a configuration fix.
+|===
+
+NOTE: A successful parse that encountered internal parser errors (e.g. a truncated
+embedded document) still returns `200 OK`. The partial-parse exception is surfaced
+in the `X-TIKA:EXCEPTION:container_exception` metadata field of the response, not as an
+HTTP error code.
+
 == Configuration
 
 Server behavior beyond host/port is controlled by a JSON config file passed via

tika-server/tika-server-core/src/main/java/org/apache/tika/server/core/TikaServerProcess.java

@@ -510,7 +510,7 @@ private static PipesParsingHelper initPipesParsingHelper(TikaServerConfig tikaSe
 
         // Create and return the helper
         PipesParsingHelper helper = new PipesParsingHelper(pipesParser, pipesConfig,
-                inputTempDirectory, unpackTempDirectory);
+                inputTempDirectory, unpackTempDirectory, tikaServerConfig.isReturnStackTrace());
 
         // Register shutdown hook to clean up PipesParser and temp directories
         final Path inputDirToClean = inputTempDirectory;

tika-server/tika-server-core/src/main/java/org/apache/tika/server/core/resource/PipesParsingHelper.java

@@ -24,7 +24,10 @@
 import java.util.List;
 import java.util.UUID;
 
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.node.ObjectNode;
 import jakarta.ws.rs.WebApplicationException;
+import jakarta.ws.rs.core.MediaType;
 import jakarta.ws.rs.core.Response;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -67,6 +70,7 @@ public class PipesParsingHelper {
     private final PipesConfig pipesConfig;
     private final Path inputTempDirectory;
     private final Path unpackEmitterBasePath;
+    private final boolean returnStackTrace;
 
     /**
      * Creates a PipesParsingHelper.
@@ -78,13 +82,19 @@ public class PipesParsingHelper {
      * @param unpackEmitterBasePath the basePath where the unpack-emitter writes files.
      *                              This is where the server will find the zip files created
      *                              by UNPACK mode. May be null if UNPACK mode won't be used.
+     * @param returnStackTrace whether failure responses may include the (potentially
+     *                         stack-trace-bearing) {@code PipesResult} message. When false
+     *                         (the default), error bodies carry only the status. Mirrors
+     *                         {@code TikaServerConfig.isReturnStackTrace()}.
      */
     public PipesParsingHelper(PipesParser pipesParser, PipesConfig pipesConfig,
-                              Path inputTempDirectory, Path unpackEmitterBasePath) {
+                              Path inputTempDirectory, Path unpackEmitterBasePath,
+                              boolean returnStackTrace) {
         this.pipesParser = pipesParser;
         this.pipesConfig = pipesConfig;
         this.inputTempDirectory = inputTempDirectory;
         this.unpackEmitterBasePath = unpackEmitterBasePath;
+        this.returnStackTrace = returnStackTrace;
 
         if (inputTempDirectory == null || !Files.isDirectory(inputTempDirectory)) {
             throw new IllegalArgumentException(
@@ -184,33 +194,60 @@ private String getSuffix(Metadata metadata) {
         return ".tmp";
     }
 
+    /**
+     * Builds a JSON error response carrying a subset of the {@code PipesResult}
+     * serialization. By default the body is just {@code {"status": "TIMEOUT"}}. The
+     * {@code PipesResult} message frequently contains a server-side stack trace
+     * (e.g. for {@code *_EXCEPTION} statuses), so the {@code message} field is included
+     * only when {@code returnStackTrace} is enabled — matching the legacy
+     * {@code TikaServerParseExceptionMapper}, which gates stack traces the same way.
+     * Successful-parse fields such as {@code emitData} are never part of an error body.
+     * <p>
+     * This allows clients to distinguish failure modes (TIMEOUT, OOM, UNSPECIFIED_CRASH, …)
+     * without parsing plain-text bodies or inspecting custom headers.
+     */
+    private Response buildProcessFailureResponse(PipesResult result) {
+        ObjectMapper mapper = new ObjectMapper();
+        ObjectNode node = mapper.createObjectNode();
+        node.put("status", result.status().name());
+        if (returnStackTrace && result.message() != null && !result.message().isBlank()) {
+            node.put("message", result.message());
+        }
+        String json;
+        try {
+            json = mapper.writeValueAsString(node);
+        } catch (Exception e) {
+            LOG.warn("Failed to serialize PipesResult error response as JSON; falling back to status-only body", e);
+            json = "{\"status\":\"" + result.status().name() + "\"}";
+        }
+        return Response.status(mapStatusToHttpResponse(result.status()))
+                .entity(json)
+                .type(MediaType.APPLICATION_JSON)
+                .build();
+    }
+
     /**
      * Processes the PipesResult and returns the metadata list.
      */
     private List<Metadata> processResult(PipesResult result) {
         if (result.isProcessCrash()) {
-            // Process crashed (OOM, timeout, etc.) - return 503
+            // Process crashed (OOM, timeout, unspecified crash) — 503 with JSON status body
             LOG.warn("Parse process crashed: {}", result.status());
-            throw new WebApplicationException(
-                    "Parse failed: " + result.status(),
-                    mapStatusToHttpResponse(result.status()));
+            throw new WebApplicationException(buildProcessFailureResponse(result));
         }
 
         if (result.isFatal() || result.isInitializationFailure()) {
-            // Fatal or initialization error - return 500
+            // Initialization/fatal error — JSON status body, HTTP status per mapStatusToHttpResponse
+            // (500, or 503 for CLIENT_UNAVAILABLE_WITHIN_MS)
             LOG.error("Parse initialization/fatal error: {} - {}",
                     result.status(), result.message());
-            throw new WebApplicationException(
-                    "Parse failed: " + result.status(),
-                    mapStatusToHttpResponse(result.status()));
+            throw new WebApplicationException(buildProcessFailureResponse(result));
         }
 
         if (result.isTaskException()) {
-            // Task-level exception (fetch/emit error) - return 500
+            // Task-level exception (fetch/emit error) — 500 with JSON status body
             LOG.warn("Parse task exception: {} - {}", result.status(), result.message());
-            throw new WebApplicationException(
-                    "Parse failed: " + result.status(),
-                    Response.Status.INTERNAL_SERVER_ERROR);
+            throw new WebApplicationException(buildProcessFailureResponse(result));
         }
 
         // Get metadata from result
@@ -241,9 +278,9 @@ public static Response.Status mapStatusToHttpResponse(PipesResult.RESULT_STATUS
                  EMIT_SUCCESS, EMIT_SUCCESS_PARSE_EXCEPTION, EMIT_SUCCESS_PASSBACK,
                  PARSE_EXCEPTION_NO_EMIT ->
                     Response.Status.OK;
-            case TIMEOUT, OOM, CLIENT_UNAVAILABLE_WITHIN_MS ->
+            case TIMEOUT, OOM, UNSPECIFIED_CRASH, CLIENT_UNAVAILABLE_WITHIN_MS ->
                     Response.Status.SERVICE_UNAVAILABLE;
-            case UNSPECIFIED_CRASH, FETCH_EXCEPTION, EMIT_EXCEPTION,
+            case FETCH_EXCEPTION, EMIT_EXCEPTION,
                  FETCHER_NOT_FOUND, EMITTER_NOT_FOUND,
                  FETCHER_INITIALIZATION_EXCEPTION, EMITTER_INITIALIZATION_EXCEPTION,
                  FAILED_TO_INITIALIZE ->
@@ -359,16 +396,12 @@ public UnpackResult parseUnpack(TikaInputStream tis, Metadata metadata,
             // Check for errors
             if (result.isProcessCrash() || result.isFatal() || result.isInitializationFailure()) {
                 LOG.warn("UNPACK parse failed: {} - {}", result.status(), result.message());
-                throw new WebApplicationException(
-                        "Parse failed: " + result.status(),
-                        mapStatusToHttpResponse(result.status()));
+                throw new WebApplicationException(buildProcessFailureResponse(result));
             }
 
             if (result.isTaskException()) {
                 LOG.warn("UNPACK task exception: {} - {}", result.status(), result.message());
-                throw new WebApplicationException(
-                        "Parse failed: " + result.message(),
-                        Response.Status.INTERNAL_SERVER_ERROR);
+                throw new WebApplicationException(buildProcessFailureResponse(result));
             }
 
             // Get metadata list from result

tika-server/tika-server-core/src/test/java/org/apache/tika/server/core/CXFTestBase.java

@@ -214,7 +214,7 @@ public void setUp() throws Exception {
             pipesConfig.setEmitStrategy(new EmitStrategyConfig(EmitStrategy.PASSBACK_ALL));
             this.pipesParser = PipesParser.load(tikaJsonConfig, pipesConfig, this.pipesConfigPath);
             PipesParsingHelper pipesParsingHelper = new PipesParsingHelper(this.pipesParser, pipesConfig,
-                    inputTempDirectory, getUnpackEmitterBasePath());
+                    inputTempDirectory, getUnpackEmitterBasePath(), false);
 
             TikaResource.init(tika, new ServerStatus(), pipesParsingHelper, isEnableUnsecureFeatures());
         } finally {

tika-server/tika-server-core/src/test/java/org/apache/tika/server/core/TikaServerIntegrationTest.java

@@ -35,6 +35,8 @@
 import java.security.GeneralSecurityException;
 import java.util.List;
 
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
 import jakarta.ws.rs.ProcessingException;
 import jakarta.ws.rs.core.Response;
 import org.apache.commons.io.IOUtils;
@@ -136,6 +138,7 @@ public void testOOM() throws Exception {
 
         // Server should return 503 (Service Unavailable) for OOM, not crash
         assertEquals(503, response.getStatus());
+        assertErrorResponseStatus(response, "OOM");
 
         // Server should still be running - verify with a successful request
         testBaseline();
@@ -155,6 +158,7 @@ public void testOOMWithPipes() throws Exception {
 
         // Server should return 503 (Service Unavailable) for OOM, not crash
         assertEquals(503, response.getStatus());
+        assertErrorResponseStatus(response, "OOM");
 
         // Server should still be running - verify with a successful request
         testBaseline();
@@ -172,8 +176,9 @@ public void testSystemExit() throws Exception {
                 .accept("application/json")
                 .put(ClassLoader.getSystemResourceAsStream(TEST_SYSTEM_EXIT));
 
-        // Server should return 500 (Internal Server Error) for unspecified crash
-        assertEquals(500, response.getStatus());
+        // UNSPECIFIED_CRASH is a transient process failure — 503, same category as OOM/TIMEOUT
+        assertEquals(503, response.getStatus());
+        assertErrorResponseStatus(response, "UNSPECIFIED_CRASH");
 
         // Server should still be running - verify with a successful request
         testBaseline();
@@ -191,8 +196,9 @@ public void testSystemExitWithPipes() throws Exception {
                 .accept("application/json")
                 .put(ClassLoader.getSystemResourceAsStream(TEST_SYSTEM_EXIT));
 
-        // Server should return 500 (Internal Server Error) for unspecified crash
-        assertEquals(500, response.getStatus());
+        // UNSPECIFIED_CRASH is a transient process failure — 503, same category as OOM/TIMEOUT
+        assertEquals(503, response.getStatus());
+        assertErrorResponseStatus(response, "UNSPECIFIED_CRASH");
 
         // Server should still be running - verify with a successful request
         testBaseline();
@@ -212,11 +218,25 @@ public void testTimeout() throws Exception {
 
         // Server should return 503 (Service Unavailable) for timeout
         assertEquals(503, response.getStatus());
+        assertErrorResponseStatus(response, "TIMEOUT");
 
         // Server should still be running - verify with a successful request
         testBaseline();
     }
 
+    /**
+     * Asserts that an error response body is JSON with a {@code status} field matching
+     * {@code expectedStatus} (a {@code PipesResult.RESULT_STATUS} enum name).
+     */
+    private void assertErrorResponseStatus(Response response, String expectedStatus) throws IOException {
+        try (InputStream is = (InputStream) response.getEntity()) {
+            String body = IOUtils.toString(is, UTF_8);
+            JsonNode node = new ObjectMapper().readTree(body);
+            assertEquals(expectedStatus, node.path("status").asText(null),
+                    "Expected JSON error body with status=" + expectedStatus + " but got: " + body);
+        }
+    }
+
 
     private String getConfig(String configName) {
         try {