apache/seatunnel · error · EasysearchConnectorException

BULK_RESPONSE_ERROR

BULK_RESPONSE_ERROR

Error message

bulk ezs error: 

What it means

EasysearchSinkWriter.bulkEzsWithRetry sends accumulated bulk request lines to the Easysearch cluster via ezsClient.bulk(). If the BulkResponse reports errors (isErrors() true — some individual items in the bulk failed), it throws a BULK_RESPONSE_ERROR containing the raw response body. This is the server acknowledging the request but rejecting one or more operations.

Source

Thrown at seatunnel-connectors-v2/connector-easysearch/src/main/java/org/apache/seatunnel/connectors/seatunnel/easysearch/sink/EasysearchSinkWriter.java:111

    @Override
    public Optional<EasysearchCommitInfo> prepareCommit() {
        bulkEzsWithRetry(this.ezsClient, this.requestEzsList);
        return Optional.empty();
    }

    @Override
    public void abortPrepare() {}

    public synchronized void bulkEzsWithRetry(
            EasysearchClient ezsClient, List<String> requestEzsList) {
        try {
            RetryUtils.retryWithException(
                    () -> {
                        if (!requestEzsList.isEmpty()) {
                            String requestBody = String.join("\n", requestEzsList) + "\n";
                            BulkResponse bulkResponse = ezsClient.bulk(requestBody);
                            if (bulkResponse.isErrors()) {
                                throw new EasysearchConnectorException(
                                        EasysearchConnectorErrorCode.BULK_RESPONSE_ERROR,
                                        "bulk ezs error: " + bulkResponse.getResponse());
                            }
                            return bulkResponse;
                        }
                        return null;
                    },
                    retryMaterial);
            requestEzsList.clear();
        } catch (Exception e) {
            throw new EasysearchConnectorException(
                    SQL_OPERATION_FAILED, "Easysearch execute batch statement error", e);
        }
    }

    @Override
    public void close() throws IOException {
        bulkEzsWithRetry(this.ezsClient, this.requestEzsList);

View on GitHub (pinned to cf67b549a7)

Solutions

1. Read the response body in the error message to identify which items failed and why (usually a mapper_parsing_exception or index_not_found).
2. Fix the mapping mismatch: correct the field types in the schema, or recreate/reindex the target index.
3. Ensure the target index exists and is open; unblock the cluster if it hit disk watermarks (free space, raise flood_stage threshold).
4. Enable per-batch retry/dead-letter handling for transient item failures in the writer config.

Example fix

// before: schema writes age as STRING into index where age is mapped INTEGER -> item error
// after: align schema with index mapping
{"age": {"type": "INT"}}

try { writer.write(row); } catch (EasysearchConnectorException e) { if (e.getSeaTunnelErrorCode() == EasysearchConnectorErrorCode.BULK_RESPONSE_ERROR) { String body = e.getMessage(); log.error("Bulk item failures, inspect response: {}", body); /* route failed docs to DLQ and re-submit */ } else { throw e; } }

When it happens

Trigger: A bulk API call returns HTTP 200 with per-item errors: document mapping conflicts (wrong type for an existing field), index not found, document too large, cluster read-only/disk watermark exceeded, or version conflicts on updates.

Common situations: Sink schema doesn't match the target index mapping; target index closed or missing; disk flood-stage watermark set cluster to read-only; bulk payload contains a document that violates dynamic mapping.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

• BULK_RESPONSE_ERROR
• SQL_OPERATION_FAILED
• Failed to open catalog ${catalogName}
• Failed to drop table ${tableName} in catalog ${catalogName}
• Failed to truncate table ${tableName} in catalog ${catalogNa

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/43685df21dc72612. Report an issue: GitHub.