apache/seatunnel · critical · CatalogException

Failed to open catalog ${catalogName}

Error message

Failed to open catalog ${catalogName}

What it means

EasysearchCatalog.open wraps client initialization in a try/catch and rethrows any exception as a CatalogException with the catalog name. It indicates the Easysearch REST client could not be created or the initial connection/verification against the cluster failed.

Source

Thrown at seatunnel-connectors-v2/connector-easysearch/src/main/java/org/apache/seatunnel/connectors/seatunnel/easysearch/catalog/EasysearchCatalog.java:89

            String catalogName, String defaultDatabase, ReadonlyConfig easySearchConfig) {
        this.catalogName = checkNotNull(catalogName, "catalogName cannot be null");
        this.defaultDatabase = defaultDatabase;
        this.pluginConfig = checkNotNull(easySearchConfig, "easySearchConfig cannot be null");
    }

    @Override
    public void open() throws CatalogException {
        try {
            ezsClient = EasysearchClient.createInstance(pluginConfig);
            EasysearchClusterInfo easysearchClusterInfo = ezsClient.getClusterInfo();
            if (LOGGER.isDebugEnabled()) {
                LOGGER.debug(
                        "Success open ezs catalog: {}, cluster info: {}",
                        catalogName,
                        easysearchClusterInfo);
            }
        } catch (Exception e) {
            throw new CatalogException(String.format("Failed to open catalog %s", catalogName), e);
        }
    }

    @Override
    public void close() throws CatalogException {
        ezsClient.close();
    }

    @Override
    public String name() {
        return catalogName;
    }

    @Override
    public String getDefaultDatabase() throws CatalogException {
        return defaultDatabase;
    }

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Verify cluster connectivity: curl the Easysearch endpoint from the job machine.
  2. Check catalog options (hosts, scheme, username, password, TLS settings) for typos.
  3. Inspect the chained cause 'e' in the stack trace for the root failure (connect timeout, 401, SSL error).
  4. If using https, import the cluster certificate into the truststore or disable/fix cert validation appropriately.

Example fix

// before
catalogs {
  easysearch {
    hosts = ["localhost:9200"]
    scheme = "https"
  }
}
// after (cluster is plain http)
catalogs {
  easysearch {
    hosts = ["localhost:9200"]
    scheme = "http"
  }
}
Defensive patterns

Strategy: try-catch

Validate before calling

// preflight connectivity
HttpGet ping = new HttpGet(host + ":" + port);
// execute with credentials; fail fast if not 200

Try / catch

try {
    catalog.open();
} catch (CatalogException e) {
    if (e.getCause() instanceof IOException || e.getCause() instanceof RuntimeException) {
        // inspect cause: connect refused vs 401 vs SSL
    }
    throw e;
}

Prevention

When it happens

Trigger: Any exception during ezsClient initialization in open(): unreachable host/port, wrong scheme (http vs https), TLS handshake failure, authentication rejection, or malformed cluster info used to build the client.

Common situations: Wrong hosts/username/password in catalog options; cluster down or firewalled; HTTPS certificate not trusted; Easysearch version endpoint not reachable behind a proxy.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

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