elastic/elasticsearch · error · ElasticsearchParseException

field [{}] has an attachment field size of [{}] bytes exceed

Error message

field [{}] has an attachment field size of [{}] bytes exceeding the maximum allowed input size {}

What it means

ElasticsearchParseException from checkMaxAttachmentFieldSize when the raw bytes of the configured attachment field exceed the node-level cap AND the operator has set ingest.attachment.max_field_size_message_suffix. The suffix replaces the default detailed tail, letting operators surface a custom hint (e.g. a documentation link) instead of the raw limit.

Source

Thrown at modules/ingest-attachment/src/main/java/org/elasticsearch/ingest/attachment/AttachmentProcessor.java:143

    /**
     * Resolves {@link #MAX_FIELD_SIZE_SETTING} to an absolute byte cap, or -1 if not applicable.
     */
    private static long resolveMaxFieldSizeFromNode(RelativeByteSizeValue maxFieldSizeFromNode) {
        if (maxFieldSizeFromNode.isAbsolute()) {
            return maxFieldSizeFromNode.getAbsolute().getBytes();
        }
        long heapMaxBytes = JvmInfo.jvmInfo().getMem().getHeapMax().getBytes();
        if (heapMaxBytes <= 0) {
            return -1L;
        }
        return maxFieldSizeFromNode.calculateValue(ByteSizeValue.ofBytes(heapMaxBytes), null).getBytes();
    }

    private void checkMaxAttachmentFieldSize(final int fieldSizeBytes) {
        if (maxFieldSizeFromNodeBytes >= 0 && fieldSizeBytes > maxFieldSizeFromNodeBytes) {
            if (Strings.hasLength(maxFieldSizeExceededMessage)) {
                throw new ElasticsearchParseException(
                    "field [{}] has an attachment field size of [{}] bytes exceeding the maximum allowed input size {}",
                    field,
                    fieldSizeBytes,
                    maxFieldSizeExceededMessage
                );
            }
            throw new ElasticsearchParseException(
                "field [{}] has an attachment field size of [{}] bytes exceeding the maximum allowed input size of [{}] bytes "
                    + "due to setting [{}={}]",
                field,
                fieldSizeBytes,
                maxFieldSizeFromNodeBytes,
                MAX_FIELD_SIZE_SETTING.getKey(),
                maxFieldSizeFromNode.getStringRep()
            );
        }
        if (maxFieldBytesFromProcessor >= 0 && fieldSizeBytes > maxFieldBytesFromProcessor) {
            throw new ElasticsearchParseException(

View on GitHub (pinned to db6a809a66)

Solutions

1. Raise ingest.attachment.max_field_size (absolute bytes or heap ratio) on the node
2. Reduce the attachment size upstream (extract text before ingest, split documents)
3. Temporarily clear the suffix setting to see the exact numeric limit for tuning

Example fix

// before
PUT _cluster/settings
{"persistent":{"ingest.attachment.max_field_size":"20%"}}
// after
PUT _cluster/settings
{"persistent":{"ingest.attachment.max_field_size":"40%"}}

// Pre-check field size against the node cap before sending large attachments:
long cap = resolveNodeCapBytes(); // from ingest.attachment.max_field_size
if (rawBytes > cap) { routeToEnrichmentStage(doc); }

try { ingest(pipeline); }
catch (ElasticsearchParseException e) { /* if message contains 'max_field_size_message_suffix' cap, route doc out */ }

When it happens

Trigger: An ingest pipeline with an attachment processor receives a document whose source field raw-byte length > maxFieldSizeFromNodeBytes, and ingest.attachment.max_field_size_message_suffix is non-empty. The first branch of checkMaxAttachmentFieldSize fires.

Common situations: Large PDFs/Office docs hitting a node heap-relative cap; base64-encoded binaries inflating size; suffix configured to point users at an upload guide.

Related errors

• field [{}] has an attachment field size of [{}] bytes exceed
• field [{}] has an attachment field size of [{}] bytes exceed
• Error parsing document in field [{}]
• document is encrypted
• field [{}] is null, cannot parse.

AI-assisted analysis of elastic/elasticsearch@db6a809a66 (2026-08-12). Data as JSON: /api/errors/584f5b9279945524. Report an issue: GitHub.