apache/seatunnel · critical · DatabendConnectorException

CONNECT_FAILED

CONNECT_FAILED

Error message

Failed to connect to Databend server: {e.getMessage()}

What it means

DatabendCatalog.open() obtains a JDBC connection via getConnection() and, if a SQLException occurs while establishing it, throws CONNECT_FAILED. The wrapped e.getMessage() carries the driver's actual reason (auth failure, DNS failure, TLS error, etc.). This is thrown when the catalog is opened before any metadata operations run.

Source

Thrown at seatunnel-connectors-v2/connector-databend/src/main/java/org/apache/seatunnel/connectors/seatunnel/databend/catalog/DatabendCatalog.java:103

    @Override
    public void dropDatabase(TablePath tablePath, boolean ignoreIfNotExists)
            throws DatabaseNotExistException, CatalogException {
        String databaseName = tablePath.getDatabaseName();
        dropDatabase(databaseName, ignoreIfNotExists);
    }

    @Override
    public void open() throws CatalogException {
        if (isOpened) {
            return;
        }

        try (Connection connection = getConnection()) {
            log.info("Successfully connected to Databend");
            isOpened = true;
        } catch (SQLException e) {
            throw new DatabendConnectorException(
                    DatabendConnectorErrorCode.CONNECT_FAILED,
                    "Failed to connect to Databend server: " + e.getMessage(),
                    e);
        }
    }

    @Override
    public void close() throws CatalogException {
        // Databend JDBC connections are closed after use
        isOpened = false;
    }

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

    @Override

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Read the wrapped SQLException message for the concrete cause and verify the url/username/password options are correct for your Databend deployment.
  2. Test connectivity from the worker host: curl -v https://databend-host:443 or run the same JDBC URL from a standalone Java/client tool.
  3. Confirm the JDBC URL format: jdbc:databend://host:port/database with ssl settings appropriate to the deployment.
  4. Check that the Databend user exists with SQL access from the worker's IP (GRANT statements / IP allowlist on DatabendCloud).

Example fix

// before
url = "jdbc:databend://localhost:8000" // wrong port/host, no credentials
// after
url = "jdbc:databend://databend-host:443/default?ssl=true"
username = "root"
password = "password"
Defensive patterns

Strategy: validation

Validate before calling

// before opening the catalog
try (Connection c = DriverManager.getConnection(url, user, pass)) {
  System.out.println("databend reachable");
} catch (SQLException e) {
  throw new IllegalStateException("pre-check failed: " + e.getMessage());
}

Try / catch

try {
  catalog.open();
} catch (DatabendConnectorException e) {
  if (e.getErrorCode() == CONNECT_FAILED) {
    log.error("connection failed: {}", e.getCause().getMessage());
    // alert / abort job before doing metadata work
  }
}

Prevention

When it happens

Trigger: Catalog open() calls getConnection() and the driver raises a SQLException: wrong JDBC URL/host/port, unreachable server, invalid username/password, TLS handshake failure, or HTTP proxy issues against the Databend query endpoint (usually port 443/8000).

Common situations: Typo in jdbc:databend:// URL, DatabendCloud vs self-hosted endpoint confusion, wrong credentials or missing user creation, network egress blocked from the SeaTunnel worker, or using port 8000 where only 443 is allowed.

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/8865d91f7bcaabf9. Report an issue: GitHub.