Implementation:Datahub project Datahub DataHubClientException

Knowledge Sources	Datahub_project_Datahub
Domains	Java_SDK, Metadata_Management
Last Updated	2026-02-10 00:00 GMT

Overview

Description

DataHubClientException is the base unchecked exception for all DataHub Java SDK V2 errors. It extends RuntimeException to maintain fluent API ergonomics and aligns with patterns from popular Java SDKs (AWS SDK, Google Cloud SDK, Stripe SDK).

The exception provides rich context about what operation failed, including:

• Entity URN - the URN of the entity involved in the failed operation
• Aspect name - the name of the aspect involved
• Operation type - the operation that failed (e.g., "fetch", "save", "parse")

All contextual fields are optional (nullable), and the cause chain is preserved for debugging. The toString() method appends all available context in a structured format.

Usage

This exception serves as the base class for all SDK-specific exception types. Users can catch DataHubClientException to handle any SDK error, or catch specific subclasses for differentiated error handling and retry logic.

Code Reference

Source Location

metadata-integration/java/datahub-client/src/main/java/datahub/client/v2/exceptions/DataHubClientException.java

Signature

public class DataHubClientException extends RuntimeException {

    public DataHubClientException(String message, Throwable cause)

    public DataHubClientException(String message)

    public DataHubClientException(
        String message,
        @Nullable Throwable cause,
        @Nullable Urn entityUrn,
        @Nullable String aspectName,
        @Nullable String operation)

    @Nullable
    public Urn getEntityUrn()

    @Nullable
    public String getAspectName()

    @Nullable
    public String getOperation()

    @Override
    public String toString()
}

Import

import datahub.client.v2.exceptions.DataHubClientException;

I/O Contract

Inputs

Constructor	Parameter	Type	Description
Simple	message	String	Error message describing what failed
With cause	message	String	Error message describing what failed
With cause	cause	Throwable	The underlying exception
Full context	message	String	Error message describing what failed
Full context	cause	Throwable (nullable)	The underlying exception
Full context	entityUrn	Urn (nullable)	URN of the entity involved
Full context	aspectName	String (nullable)	Name of the aspect involved
Full context	operation	String (nullable)	The failed operation (e.g., "fetch", "save")

Outputs

Method	Return Type	Description
getEntityUrn	Urn (nullable)	The entity URN, or null if not applicable
getAspectName	String (nullable)	The aspect name, or null if not applicable
getOperation	String (nullable)	The operation name, or null if not specified
toString	String	Message with appended context fields (entityUrn, aspectName, operation)

Usage Examples

// Simple exception
throw new DataHubClientException("Failed to connect to DataHub server");

// Exception with cause
try {
    // network operation
} catch (IOException e) {
    throw new DataHubClientException("Network error during fetch", e);
}

// Exception with full context
throw new DataHubClientException(
    "Failed to fetch aspect",
    cause,
    entityUrn,
    "ownership",
    "fetch"
);

// Catching SDK exceptions
try {
    client.entities().upsert(dataset);
} catch (DataHubClientException e) {
    System.err.println("Entity: " + e.getEntityUrn());
    System.err.println("Aspect: " + e.getAspectName());
    System.err.println("Operation: " + e.getOperation());
}

Related Pages

• Datahub_project_Datahub_PendingMutationsException - Subclass for reads on entities with pending mutations
• Datahub_project_Datahub_ReadOnlyEntityException - Subclass for mutations on read-only entities