elastic/elasticsearch · error · IllegalArgumentException

unable to calculate network direction from document

Error message

unable to calculate network direction from document

What it means

Thrown by NetworkDirectionProcessor.execute when getDirection(ingestDocument) returns null — meaning the processor could not determine a network direction from the available fields. The processor requires source/destination IP and configured network lists; if any required input is missing or none of the configured networks match, direction stays null. IllegalArgumentException when ignoreMissing=false; otherwise the document passes through unchanged.

Source

Thrown at modules/ingest-common/src/main/java/org/elasticsearch/ingest/common/NetworkDirectionProcessor.java:89

        return internalNetworks;
    }

    public String getInternalNetworksField() {
        return internalNetworksField;
    }

    public boolean getIgnoreMissing() {
        return ignoreMissing;
    }

    @Override
    public IngestDocument execute(IngestDocument ingestDocument) throws Exception {
        String direction = getDirection(ingestDocument);
        if (direction == null) {
            if (ignoreMissing) {
                return ingestDocument;
            } else {
                throw new IllegalArgumentException("unable to calculate network direction from document");
            }
        }

        ingestDocument.setFieldValue(targetField, direction);
        return ingestDocument;
    }

    private String getDirection(IngestDocument d) throws Exception {
        List<String> networks = new ArrayList<>();

        if (internalNetworksField != null) {
            @SuppressWarnings("unchecked")
            List<String> stringList = d.getFieldValue(internalNetworksField, networks.getClass(), ignoreMissing);
            if (stringList == null) {
                return null;
            }
            networks.addAll(stringList);
        } else {

View on GitHub (pinned to db6a809a66)

Solutions

1. Set "ignore_missing": true to pass through documents that can't be classified.
2. Ensure source_ip/destination_ip/internal_networks/categories fields are populated upstream.
3. Verify the internal_networks / external_networks chain includes the relevant CIDR ranges.
4. Gate the processor with a conditional that checks required fields exist.

Example fix

// before
{"network_direction": {"source_ip": "src", "destination_ip": "dst"}}
// after
{"network_direction": {"source_ip": "src", "destination_ip": "dst", "ignore_missing": true}}

// Pre-check required IP fields exist before invoking processor
if (!doc.hasField(sourceIp) || !doc.hasField(destIp)) {
    if (!ignoreMissing) {
        // set ignore_missing or skip document
    }
}

static boolean canComputeDirection(IngestDocument doc, String src, String dst) {
    return doc.hasField(src) && doc.hasField(dst);
}

try {
    ndProcessor.execute(doc);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("unable to calculate network direction")) {
        // route unclassifiable docs elsewhere
    } else throw e;
}

When it happens

Trigger: Document lacks required source/destination IP fields, or internal/external network lists are empty/misconfigured, so no direction can be computed.

Common situations: Source data missing IP fields (e.g. non-network log), categories field absent, internal_networks not configured, or destination IP field path wrong.

Related errors

• field [{}] doesn't exist
• unsupported ECS compatibility mode [{}]
• field [{}] is null, cannot process it.
• unable to construct flow from document
• supports only [{}] as method

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