apache/seatunnel · error · IllegalArgumentException

Could not find field with name ${fieldName} .

Error message

Could not find field with name ${fieldName} .

What it means

Thrown by JsonToRowConverters.convertField when a JSON node does not contain the requested field and failOnMissingField is true. The format validates strictly so that missing JSON fields surface loudly instead of silently producing null rows. If failOnMissingField is false, it returns null instead of throwing.

Source

Thrown at seatunnel-formats/seatunnel-format-json/src/main/java/org/apache/seatunnel/format/json/JsonToRowConverters.java:504

                                            throw CommonError.jsonOperationError(
                                                    FORMAT, entry.getKey(), e);
                                        }
                                        value.put(
                                                keyConverter.convert(keyNode, fieldName + ".key"),
                                                valueConverter.convert(
                                                        entry.getValue(), fieldName + ".value"));
                                    }
                                });
                return value;
            }
        };
    }

    private Object convertField(
            JsonToObjectConverter fieldConverter, String fieldName, JsonNode field) {
        if (field == null) {
            if (failOnMissingField) {
                throw new IllegalArgumentException(
                        String.format("Could not find field with name %s .", fieldName));
            } else {
                return null;
            }
        } else {
            return fieldConverter.convert(field, fieldName);
        }
    }

    private JsonToObjectConverter wrapIntoNullableConverter(JsonToObjectConverter converter) {
        return new JsonToObjectConverter() {
            @Override
            public Object convert(JsonNode jsonNode, String fieldName) {
                if (jsonNode == null || jsonNode.isNull() || jsonNode.isMissingNode()) {
                    return null;
                }
                try {
                    return converter.convert(jsonNode, fieldName);

View on GitHub (pinned to cf67b549a7)

Solutions

1. Add the missing field to the incoming JSON payload or fix the key name to match the declared row type
2. Set json.fail-on-missing-field=false (JsonParseOptions.FAIL_ON_MISSING_FIELD) so missing fields deserialize as null
3. Align the SeaTunnelRowType schema in the config with the actual JSON structure (remove or rename fields)
4. Pre-validate sample payloads against the configured schema before running the job

Example fix

// before (config)
json {
  fail-on-missing-field = true
}
// after
json {
  fail-on-missing-field = false
  ignore-parse-errors = true
}

// Java: verify payload keys against row type before deserializing
for (String field : rowType.getFieldNames()) {
    if (!jsonNode.has(field)) {
        throw new IllegalStateException("Missing field: " + field);
    }
}

if (jsonNode != null && jsonNode.isObject() && jsonNode.has(fieldName)) { /* safe to convert */ }

try { row = converter.convert(jsonNode); } catch (IllegalArgumentException e) { if (e.getMessage().contains("Could not find field")) { /* handle missing field */ } else { throw e; } }

When it happens

Trigger: Deserializing a JSON payload whose object lacks a key the configured SeaTunnelRowType expects, with failOnMultiFields/failOnMissingField enabled; convertField receives a null field node from convertedField lookup.

Common situations: Upstream producers changed their JSON schema (renamed or dropped a key); optional fields absent in some messages; parsing CDC/debezium-like payloads where nested fields vary per event; row type declared in SeaTunnel config is stricter than the actual data.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• UNSUPPORTED_DATA_TYPE
• COMMON-02
• Unsupported type:
• PACKET_DECODE_ERROR
• FileConnectorErrorCode.DATA_DESERIALIZE_FAILED

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