apache/seatunnel · error · ElasticsearchConnectorException

ADD_FIELD_FAILED

ADD_FIELD_FAILED

Error message

PUT {endpoint} response null

What it means

EsRestClient adds/updates a field by PUTting a mapping update to the index; if performRequest returns a null Response it throws ADD_FIELD_FAILED. This means the mapping-update request never yielded an HTTP answer, so the new field could not be applied to the index schema.

Source

Thrown at seatunnel-connectors-v2/connector-elasticsearch/src/main/java/org/apache/seatunnel/connectors/seatunnel/elasticsearch/client/EsRestClient.java:896

                    .getType()
                    .equalsIgnoreCase(AGGREGATE_METRIC_DOUBLE)) {
                ArrayNode metricsArray = OBJECT_MAPPER.createArrayNode();
                @SuppressWarnings("unchecked")
                List<String> metrics = (List<String>) options.get("metrics");
                metrics.forEach(metricsArray::add);
                fieldJson.set("metrics", metricsArray);
            }
        }

        propertiesJson.set(fieldTypeDefine.getName(), fieldJson);
        mappingJson.set("properties", propertiesJson);

        request.setJsonEntity(mappingJson.toString());

        try {
            Response response = restClient.performRequest(request);
            if (response == null) {
                throw new ElasticsearchConnectorException(
                        ElasticsearchConnectorErrorCode.ADD_FIELD_FAILED,
                        "PUT " + endpoint + " response null");
            }
            String entity = EntityUtils.toString(response.getEntity(), StandardCharsets.UTF_8);
            if (response.getStatusLine().getStatusCode() != HttpStatus.SC_OK) {
                throw new ElasticsearchConnectorException(
                        ElasticsearchConnectorErrorCode.ADD_FIELD_FAILED,
                        String.format(
                                "PUT %s response status code=%d, body=%s",
                                endpoint, response.getStatusLine().getStatusCode(), entity));
            }
        } catch (IOException ex) {
            throw new ElasticsearchConnectorException(
                    ElasticsearchConnectorErrorCode.ADD_FIELD_FAILED,
                    String.format(
                            "Failed to add field %s to index %s", fieldTypeDefine.getName(), index),
                    ex);
        }

View on GitHub (pinned to cf67b549a7)

Solutions

1. Verify the ES cluster is reachable and the PUT /{index}/_mapping call works with curl
2. Retry the job — auto-add-field is often transient-safe once connectivity is restored
3. If using a custom client wrapper, ensure it throws IOException rather than returning null
4. Pre-create the field mapping in the index definition so runtime addField is unnecessary

// check the index accepts mapping updates
curl -s -u user:pass 'es:9200/<index>/_settings?filter_path=*.blocks*'
curl -s -o /dev/null -w '%{http_code}' 'es:9200/<index>'

if (response == null) { throw new IOException("null response for mapping PUT on " + index); }

try {
    esRestClient.addField(index, fieldTypeDefine);
} catch (ElasticsearchConnectorException e) {
    // retry with backoff; check cause for network faults
}

When it happens

Trigger: Calling the addField path (PUT /{index}/_mapping with the field's mapping JSON) when restClient.performRequest(request) returns null.

Common situations: Custom/mock RestClient returning null; connection dropped by a proxy mid-request; wrapped client versions where the null case is reachable during network faults.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

• GET_INDEX_DOCS_COUNT_FAILED
• LIST_INDEX_FAILED
• CREATE_INDEX_FAILED
• DROP_INDEX_FAILED
• CLEAR_INDEX_DATA_FAILED

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