apache/seatunnel · error · CatalogException

Failed to open catalog %s

Error message

Failed to open catalog %s

What it means

MilvusCatalog.open builds a ConnectParam from the configured URL and token and instantiates a MilvusServiceClient. Any exception from the Milvus SDK during client construction is wrapped in CatalogException with 'Failed to open catalog <name>'. This indicates the catalog could not establish a gRPC connection to the Milvus server.

Source

Thrown at seatunnel-connectors-v2/connector-milvus/src/main/java/org/apache/seatunnel/connectors/seatunnel/milvus/catalog/MilvusCatalog.java:101

    private MilvusServiceClient client;

    public MilvusCatalog(String catalogName, ReadonlyConfig config) {
        this.catalogName = catalogName;
        this.config = config;
    }

    @Override
    public void open() throws CatalogException {
        ConnectParam connectParam =
                ConnectParam.newBuilder()
                        .withUri(config.get(MilvusSinkOptions.URL))
                        .withToken(config.get(MilvusSinkOptions.TOKEN))
                        .build();
        try {
            this.client = new MilvusServiceClient(connectParam);
        } catch (Exception e) {
            throw new CatalogException(String.format("Failed to open catalog %s", catalogName), e);
        }
    }

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

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

    @Override
    public PreviewResult previewAction(
            ActionType actionType, TablePath tablePath, Optional<CatalogTable> catalogTable) {
        if (actionType == ActionType.CREATE_TABLE) {
            return new InfoPreviewResult("create collection " + tablePath.getTableName());

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Verify the configured Milvus URL (scheme, host, port) and test reachability, e.g. with a Milvus SDK quick connect or `nc -zv host 19530`.
  2. Check the token/credentials match the Milvus instance's auth configuration.
  3. Match TLS/HTTP scheme to the server configuration (http:// vs https://, insecure vs secure channel).
  4. Inspect the wrapped cause 'e' in the stack trace for the underlying gRPC status code.

Example fix

// before
url = "http://milvus-svc:19531"
// after
url = "http://milvus-svc:19530"
Defensive patterns

Strategy: try-catch

Validate before calling

// pre-flight connectivity check
String url = config.get(MilvusSinkOptions.URL);
URI uri = new URI(url);
try (Socket s = new Socket()) {
    s.connect(new InetSocketAddress(uri.getHost(), uri.getPort()), 3000); // throws if unreachable
}

Try / catch

try {
    catalog.open(catalogConfig);
} catch (CatalogException e) {
    log.error("Milvus catalog open failed for '{}': check URL/token/TLS. Cause: {}", catalogName, e.getCause());
    throw e;
}

Prevention

When it happens

Trigger: MilvusCatalog.open() called with an unreachable/incorrect URL, an invalid token, TLS mismatch, or when the Milvus server refuses the gRPC handshake.

Common situations: Milvus server not started or wrong host:port in the connector config; auth (token/user-password) mismatch against a Milvus instance with authorization enabled; connecting over HTTPS to a plaintext endpoint or vice versa; Kubernetes network policy / service DNS not resolvable from the SeaTunnel job.

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/6f3a80b6f40fba70. Report an issue: GitHub.