apache/seatunnel · error · CatalogException

Failed connecting to

Error message

Failed connecting to %s via JDBC.

What it means

After loading the MySQL driver, StarRocksSinkWriter.applySchemaChange opens a JDBC connection to the StarRocks FE using sinkConfig.getJdbcUrl() and calls SchemaUtils.applySchemaChange. Any SQLException from the connect/DDL sequence is wrapped as CatalogException "Failed connecting to %s via JDBC." with the JDBC URL in the message and the SQLException as cause. It indicates the sink could not complete the schema change over the MySQL protocol connection.

Solutions

  1. Verify the JDBC URL points at the StarRocks FE MySQL query port (default 9030) and is network-reachable from the SeaTunnel node (test with `mysql -h <host> -P 9030`).
  2. Check username/password and that the account has ALTER privilege on the target database.
  3. Read the cause SQLException in the stack trace for the server-side message (e.g. unsupported schema change) and adjust the schema change event or target table.
  4. Confirm target table/database names in the sink config match an existing StarRocks table.

Example fix

// before
jdbc_url = "jdbc:mysql://fe-host:8030/db"
// after
jdbc_url = "jdbc:mysql://fe-host:9030/db"
Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-flight: check FE connectivity and credentials from the job node
try (Connection c = DriverManager.getConnection(
        "jdbc:mysql://fe-host:9030/db", user, pass)) {
    System.out.println("StarRocks FE reachable");
} catch (SQLException e) {
    System.err.println("FE unreachable or bad credentials: " + e.getMessage());
}

Try / catch

try {
    applySchemaChange(event);
} catch (CatalogException e) {
    if (e.getMessage().startsWith("Failed connecting to")) {
        // inspect e.getCause() (SQLException) for server message: connectivity vs rejected DDL
    }
}

Prevention

When it happens

Trigger: DriverManager.getConnection(jdbcUrl, username, password) failing (unreachable FE, wrong port, bad credentials) or SchemaUtils.applySchemaChange throwing SQLException while executing ALTER/DDL against sinkTablePath.

Common situations: Wrong jdbc_url host/port for StarRocks FE (query port vs http port confusion); firewall blocking 9030; incorrect username/password or missing database privileges; StarRocks rejecting an ALTER statement (unsupported column change) reported as SQLException.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

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

Appendix: source

Thrown at seatunnel-connectors-v2/connector-starrocks/src/main/java/org/apache/seatunnel/connectors/seatunnel/starrocks/sink/StarRocksSinkWriter.java:105

        this.tableSchema = tableSchemaChangeEventDispatcher.reset(tableSchema).apply(event);
        SeaTunnelRowType seaTunnelRowType = tableSchema.toPhysicalRowDataType();
        this.serializer = createSerializer(sinkConfig, seaTunnelRowType);
        this.manager = new StarRocksSinkManager(sinkConfig, tableSchema);

        try {
            Class.forName("com.mysql.cj.jdbc.Driver");
        } catch (ClassNotFoundException e) {
            throw new RuntimeException("Failed to load MySQL JDBC driver", e);
        }

        try (Connection conn =
                DriverManager.getConnection(
                        sinkConfig.getJdbcUrl(),
                        sinkConfig.getUsername(),
                        sinkConfig.getPassword())) {
            SchemaUtils.applySchemaChange(event, conn, sinkTablePath);
        } catch (SQLException e) {
            throw new CatalogException(
                    String.format("Failed connecting to %s via JDBC.", sinkConfig.getJdbcUrl()), e);
        }
    }

    /**
     * Exposes the resolved StarRocks target table so shared-sink schema changes can be broadcast to
     * every sibling writer that commits to the same physical table.
     */
    @Override
    public Optional<String> getPhysicalSinkTableIdentifier() {
        return sinkTablePath == null ? Optional.empty() : Optional.of(sinkTablePath.getFullName());
    }

    @SneakyThrows
    @Override
    public Optional<Void> prepareCommit() {
        // Flush to storage before snapshot state is performed
        manager.flush();

View on GitHub (pinned to cf67b549a7)