[Bug] REST API error response only contains top-level message, hiding root cause

[vanasys]

[Bug] REST API error response only contains top-level message, hiding root cause

Environment

• SeaTunnel Version: 2.3.13
• Deployment Mode: SeaTunnel Engine (Zeta) cluster
• REST API Endpoint: POST /hazelcast/rest/maps/submit-job

Problem Description

When submitting a job via the REST API and the job fails during initialization, the returned JSON error response only contains the top-level exception message (e.g., Factory initialize failed). The actual root cause — which is usually nested inside the Caused by chain — is completely lost in the HTTP response.

This makes remote debugging extremely difficult because callers of the REST API have no idea what really went wrong (e.g., missing required options, SQL syntax errors, connection timeouts, permission issues).

Steps to Reproduce

1. Start SeaTunnel cluster.
2. Submit a deliberately broken job via REST API:

   curl -X POST http://127.0.0.1:5802/hazelcast/rest/maps/submit-job \
     -H "Content-Type: application/json" \
     -d '{
       "env": {"job.mode": "BATCH"},
       "source": [{"FakeSource": {"row.num": 1}}],
       "sink": [{"Doris": {"fenodes": "127.0.0.1:8030"}}]
     }'

3. Observe the HTTP response:

   {
     "status": "fail",
     "message": "Factory initialize failed"
   }

4. Compare with the server log logs/seatunnel-engine-server.log, which contains the full Caused by stack trace.

Root Cause Analysis

In seatunnel-starter.jar, the class org.apache.seatunnel.engine.server.rest.filter.ExceptionHandlingFilter handles exceptions thrown during REST request processing.

Currently, in the handleException method, it only calls:

errResponse.setMessage(exception.getMessage());

It does not recursively traverse Throwable.getCause(), so all nested exception information is discarded before being serialized back to the HTTP client.

Expected Behavior

The REST API should return the full error chain so that remote callers can understand the root cause without logging into the server.

Expected response example:

{
  "status": "fail",
  "message": "Factory initialize failed | Caused by: OptionValidationException: the options('database') are required."
}

Suggested Fix

Modify ExceptionHandlingFilter to build a full error message by recursively walking the exception chain:

private String buildFullErrorMessage(Throwable throwable) {
    StringBuilder sb = new StringBuilder();
    sb.append(throwable.getMessage());
    Throwable cause = throwable.getCause();
    while (cause != null) {
        sb.append(" | Caused by: ")
          .append(cause.getClass().getSimpleName())
          .append(": ")
          .append(cause.getMessage());
        cause = cause.getCause();
    }
    return sb.toString().replace("\"", "'");
}

Then use buildFullErrorMessage(exception) instead of exception.getMessage() when constructing the error response.

Additional Context

• This issue affects all REST API clients that rely on the HTTP response for diagnostics.
• Server-side logs do contain the full stack trace, but in production environments, REST API users often do not have direct access to the server filesystem.
• I have verified that patching ExceptionHandlingFilter.class in seatunnel-starter.jar with the above logic resolves the issue locally.

[davidzollo]

Thanks for the detailed report.

I checked this against both 2.3.13 and the current dev branch. The behavior you described is valid for 2.3.13: ExceptionHandlingFilter#handleException writes only e.getMessage() into the REST error response, so a wrapped initialization failure such as Factory initialize failed can hide the real nested cause from REST API callers.

This path appears to have already been improved on dev by PR #10696. In the current dev code, the same filter writes ExceptionUtils.getStackTrace(e) to the response message, so the nested Caused by chain should be visible to the REST caller as well as in the server log.

So I would treat this as already fixed in dev, but still affecting the released 2.3.13 package you tested.

Please verify with either:

1. a build from the current dev branch, or
2. the next release that contains PR [Improve][Zeta] Enhance exception logging for task submission via RESTful API #10696.

If the root cause is still hidden there, please update this issue with the exact REST response body and the corresponding server-side exception stack, and we can continue checking the remaining path. One follow-up worth considering separately is whether the REST response should expose a shorter structured error chain instead of the full stack trace, to keep diagnostics useful while avoiding accidental leakage of sensitive connection details.

[vanasys]

Thanks for the confirmation! Glad to see this already fixed in dev via PR #10696. I'll verify with the next release and update if anything is still missing.

Regarding the follow-up about structured error chain vs full stack trace — a shorter structured format (e.g., message + Caused by chain without full line numbers) would indeed be a good balance between diagnostics and security.