apache/seatunnel · error · CatalogException

Failed to open catalog %s

Error message

Failed to open catalog %s

What it means

ElasticSearchCatalog.open failed to initialize the Elasticsearch catalog — typically creating/connecting the REST client and fetching cluster info — and wraps any exception in CatalogException 'Failed to open catalog <name>'. This fails job initialization before any source/sink can operate.

Source

Thrown at seatunnel-connectors-v2/connector-elasticsearch/src/main/java/org/apache/seatunnel/connectors/seatunnel/elasticsearch/catalog/ElasticSearchCatalog.java:91

    public ElasticSearchCatalog(String catalogName, String defaultDatabase, ReadonlyConfig config) {
        this.catalogName = checkNotNull(catalogName, "catalogName cannot be null");
        this.defaultDatabase = defaultDatabase;
        this.config = checkNotNull(config, "elasticSearchConfig cannot be null");
    }

    @Override
    public void open() throws CatalogException {
        try {
            esRestClient = EsRestClient.createInstance(config);
            ElasticsearchClusterInfo elasticsearchClusterInfo = esRestClient.getClusterInfo();
            if (LOGGER.isDebugEnabled()) {
                LOGGER.debug(
                        "Success open es catalog: {}, cluster info: {}",
                        catalogName,
                        elasticsearchClusterInfo);
            }
        } catch (Exception e) {
            throw new CatalogException(String.format("Failed to open catalog %s", catalogName), e);
        }
    }

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

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

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

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Verify Elasticsearch is reachable: `curl -u user:pass http://<host>:9200/` from the SeaTunnel node.
  2. Check catalog config: hosts list, http/https scheme, username/password, and TLS/truststore settings.
  3. Fix authentication — wrong or missing credentials surface here; confirm with the same credentials via curl.
  4. Inspect the root cause chained in the CatalogException (the original exception) to pinpoint connection vs auth vs TLS failure.

Example fix

// before
Elasticsearch {
  hosts = ["https://es-node:9200"] // cluster actually serves http
}
// after
Elasticsearch {
  hosts = ["http://es-node:9200"]
  username = "elastic"
  password = "***"
}
Defensive patterns

Strategy: try-catch

Validate before calling

// health-check before opening the catalog
HttpURLConnection c = (HttpURLConnection) new URL("http://es-node:9200/").openConnection();
c.setConnectTimeout(5000);
if (c.getResponseCode() != 200) throw new IllegalStateException("Elasticsearch unreachable");

Try / catch

try {
    catalog.open();
} catch (CatalogException e) {
    log.error("catalog open failed; root cause: {}", e.getCause(), e);
    // classify cause: UnknownHost/ConnectException vs auth 401 vs TLS handshake
}

Prevention

When it happens

Trigger: open() is called and the underlying EsRestClient creation or cluster-info query throws — unreachable hosts, wrong address/port scheme, authentication failures (401/403), TLS/SSL handshake problems, or Elasticsearch returning an unexpected error.

Common situations: Elasticsearch is down or firewalled; mistyped hosts or protocol (http vs https); wrong username/password or missing credentials; self-signed certificates without proper truststore config; version incompatibility between the client and the ES cluster.

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/931738a1c0229cb7. Report an issue: GitHub.