apache/seatunnel · critical · CatalogException

Failed connecting to the configured JDBC URL via JDBC.

Error message

Failed connecting to the configured JDBC URL via JDBC.

What it means

AbstractJdbcCatalog.getConnection() could not establish a JDBC connection to the configured URL via DriverManager, and wraps the SQLException in CatalogException. This is a generic 'cannot connect to the database' error raised when opening connections for catalog metadata operations.

Source

Thrown at seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/catalog/AbstractJdbcCatalog.java:155

                        try {
                            Connection connection = driver.connect(url, info);
                            connectionMap.put(url, connection);
                            return connection;
                        } catch (Exception e) {
                            log.info("try connector failed", e);
                        }
                    }
                }
            } catch (Exception e) {
                log.info("find driver error, back to DriverManager.getConnection", e);
            }
        }
        try {
            Connection connection = DriverManager.getConnection(url, info);
            connectionMap.put(url, connection);
            return connection;
        } catch (SQLException e) {
            throw new CatalogException("Failed connecting to the configured JDBC URL via JDBC.", e);
        }
    }

    protected @NonNull Properties getConnectionProperties() {
        Properties info = new Properties();
        if (username != null) {
            info.put("user", username);
        }
        if (pwd != null) {
            info.put("password", pwd);
        }
        return info;
    }

    @Override
    public void open() throws CatalogException {
        getConnection(defaultUrl);
        LOG.info("Catalog {} established connection to {}", catalogName, defaultUrl);

View on GitHub (pinned to cf67b549a7)

Solutions

1. Test the same JDBC URL/username/password with a standalone JDBC client from the SeaTunnel node.
2. Verify the JDBC driver jar is present (driver class registered) for the target database.
3. Check network reachability: host, port, firewall, VPC rules.
4. Validate the JDBC URL format and parameters for the dialect.
5. Check DB server logs and auth (user exists, correct password, allowed hosts).

Example fix

// before
url = "jdbc:mysql://localhst:3306/db"
// after
url = "jdbc:mysql://localhost:3306/db?useSSL=false"

try (Connection c = DriverManager.getConnection(url, user, pass)) { /* ok */ } catch (SQLException e) { /* fail fast pre-job with clear message */ }

catch (CatalogException e) { if (e.getCause() instanceof SQLException sqlEx) { log.error("JDBC connect failed: state={} msg={}", sqlEx.getSQLState(), sqlEx.getMessage()); } }

When it happens

Trigger: DriverManager.getConnection(url, info) throws SQLException inside getConnection(); called by open(), conn(), queryString(), querySQLResultExists(), executeInternal(), defaultConnection() during catalog metadata access.

Common situations: Wrong host/port in JDBC URL; database server down; missing JDBC driver on the classpath (no suitable driver); bad credentials; network/firewall/TLS issues; URL malformed for the specific dialect.

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

• CONNECT_FAILED
• Failed connecting to the configured JDBC URL via JDBC.
• Failed to close catalog
• Failed to get connection, interrupted while doing another at
• Get connection failed after retry times

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