apache/seatunnel · error · JdbcConnectorException

CONNECT_DATABASE_FAILED

CONNECT_DATABASE_FAILED

Error message

Sink table %s does not exist and schema_save_mode is %s.

What it means

During sink validation (dry-run), if the target table does not exist and schema_save_mode=ERROR_WHEN_SCHEMA_NOT_EXIST, JdbcSinkFactory throws CONNECT_DATABASE_FAILED stating the sink table is missing. This is a user-configuration guard: the library is told to fail rather than auto-create the schema.

Source

Thrown at seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/sink/JdbcSinkFactory.java:310

                    dialect.getJdbcConnectionProvider(sinkConfig.getJdbcConnectionConfig())
                            .getOrEstablishConnection()) {
                return;
            }
        }

        try (Catalog catalog = optionalCatalog.get()) {
            catalog.open();

            TablePath targetTablePath = resolveDryRunTargetTablePath(context);
            if (targetTablePath == null) {
                // Custom-query sink or unresolvable table name: connectivity is all we can check.
                return;
            }

            if (!catalog.tableExists(targetTablePath)) {
                if (config.get(JdbcSinkOptions.SCHEMA_SAVE_MODE)
                        == SchemaSaveMode.ERROR_WHEN_SCHEMA_NOT_EXIST) {
                    throw new JdbcConnectorException(
                            JdbcConnectorErrorCode.CONNECT_DATABASE_FAILED,
                            String.format(
                                    "Sink table %s does not exist and schema_save_mode is %s.",
                                    targetTablePath.getFullName(),
                                    SchemaSaveMode.ERROR_WHEN_SCHEMA_NOT_EXIST));
                }
                // Table will be created by save mode at runtime; nothing more to validate.
                return;
            }

            CatalogTable targetTable = catalog.getTable(targetTablePath);
            Set<String> targetColumns =
                    targetTable.getTableSchema().getColumns().stream()
                            .map(column -> column.getName().toLowerCase(Locale.ROOT))
                            .collect(Collectors.toSet());
            List<String> missingColumns =
                    context.getCatalogTable().getTableSchema().getColumns().stream()
                            .map(Column::getName)

View on GitHub (pinned to cf67b549a7)

Solutions

1. Create the target table in the database before running the job, or set schema_save_mode=CREATE_SCHEMA_WHEN_NOT_EXIST (or other auto mode) in the sink config
2. Check the database/table name spelling and that the connection URL points to the intended database/schema
3. Verify the job's user has permission to see the table (some catalogs hide tables from unprivileged users)
4. If auto-creating, also review schema_save_mode-related options like template sql to control the generated DDL

Example fix

// before
sink {
  Jdbc {
    schema_save_mode = "ERROR_WHEN_SCHEMA_NOT_EXIST"
  }
}
// after
sink {
  Jdbc {
    schema_save_mode = "CREATE_SCHEMA_WHEN_NOT_EXIST"
  }
}

// before the job: check table existence
try (Connection c = DriverManager.getConnection(url, user, pass);
     ResultSet rs = c.getMetaData().getTables(null, schema, table, new String[]{"TABLE"})) {
  if (!rs.next()) {
    // create table or set schema_save_mode = CREATE_SCHEMA_WHEN_NOT_EXIST
  }
}

try {
  sinkFactory.createSink(context);
} catch (JdbcConnectorException e) {
  if (e.getMessage().contains("does not exist")) {
    // create the table, then resubmit the job
  }
}

When it happens

Trigger: Running a job (or its validation phase, validateConnectionForDryRun) where catalog.tableExists(targetTablePath) returns false and the config has schema_save_mode = ERROR_WHEN_SCHEMA_NOT_EXIST.

Common situations: Typo in table/database name in the sink config; table expected to be pre-created by a DBA but not yet created; wrong catalog/database URL pointing at another schema; migrating jobs between environments where the table only exists in one.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Schema config can not be empty
• '%s' must be configured when '%s' is used
• %s[%d]: '%s' must be configured
• Schema config need option [schema], please correct your conf
• Schema config can't contains both [fields] and [columns], pl

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