Package org.elasticsearch.xpack.esql.datasources.spi

Class ExternalException

java.lang.Object
java.lang.Throwable
java.lang.Exception
java.lang.RuntimeException
org.elasticsearch.ElasticsearchException
org.elasticsearch.xpack.esql.core.QlException
org.elasticsearch.xpack.esql.datasources.spi.ExternalException
All Implemented Interfaces:
Serializable, Writeable, ToXContent, ToXContentFragment
Direct Known Subclasses:
ExternalClientException, ExternalServerException, ExternalUnavailableException
public abstract class ExternalException extends QlException
Base type for failures raised while reading from an external data source — an object store, a file in some columnar/row format, a remote HTTP endpoint, etc. Grouping every external-source failure under one type lets callers catch them as a family (catch (ExternalException)) and lets AsyncExternalSourceOperator surface them with the correct HTTP status.

The distinction between server- and client-class failures is carried by the concrete subtype, so the right status falls out of the exception itself rather than from a downstream instanceof ladder:

Subtypes extend QlException (rather than QlClientException/QlServerException) so they can share this single umbrella while each pinning its own status.

Transport behaviour. Like every other ES|QL exception, these are not registered in ElasticsearchException's serialization registry, so crossing a node boundary turns them into a NotSerializableExceptionWrapper. That wrapper preserves ElasticsearchException.status() (it captures ExceptionsHelper.status(this) on the sending node and replays it on the receiver), so the 400/500/503 distinction survives the data-node → coordinator hop and the REST layer still maps it correctly. What does not survive is the concrete Java type: a remote receiver cannot instanceof-check these. That is fine because classification happens co-located with the throw — ExternalFailures.classify runs inside AsyncExternalSourceOperator, which executes on the node that reads the external source, before any serialization — so no remote consumer ever needs the concrete type, only the status.

See Also:

  • Constructor Details

    • ExternalException

      protected ExternalException(String message, Throwable cause)

    • ExternalException

      protected ExternalException(Throwable cause, String message, Object... args)

    • ExternalException

      protected ExternalException(String message, Object... args)