What causes "Failed to build Salesforce table configs" in apache/seatunnel?

Inspect the attached cause exception (print the full stack trace) — it names the real failure

apache/seatunnel · error · SalesforceConnectorException

DESCRIBE_OBJECT_FAILED

DESCRIBE_OBJECT_FAILED

Error message

Failed to build Salesforce table configs

What it means

Generic wrapper thrown by SalesforceSource.buildTableConfigs when building table configurations fails with an unexpected (non-SalesforceConnectorException) exception. The original exception is attached as the cause and DESCRIBE_OBJECT_FAILED is used as the error code.

Source

Thrown at seatunnel-connectors-v2/connector-salesforce/src/main/java/org/apache/seatunnel/connectors/seatunnel/salesforce/source/SalesforceSource.java:96

                    if (duplicate) {
                        throw new SalesforceConnectorException(
                                SalesforceConnectorErrorCode.DUPLICATE_OBJECT,
                                "Duplicate object in tables_configs: " + tableId);
                    }
                    configs.add(built);
                }
                return configs;
            } else {
                String objectName = config.get(SalesforceSourceOptions.OBJECT_NAME);
                String soql = buildSoql(config, objectName);
                CatalogTable table = client.describeObject(PLUGIN_NAME, objectName);
                return Collections.singletonList(
                        new SalesforceTableConfig(soql, objectName, table));
            }
        } catch (SalesforceConnectorException e) {
            throw e;
        } catch (Exception e) {
            throw new SalesforceConnectorException(
                    SalesforceConnectorErrorCode.DESCRIBE_OBJECT_FAILED,
                    "Failed to build Salesforce table configs",
                    e);
        }
    }

    private SalesforceTableConfig buildOneTableConfig(
            ReadonlyConfig tableConfig, SalesforceClient client) {
        String tablePath =
                tableConfig
                        .getOptional(SalesforceSourceOptions.TABLE_PATH)
                        .orElseThrow(
                                () ->
                                        new SalesforceConnectorException(
                                                SalesforceConnectorErrorCode.INVALID_TABLE_PATH,
                                                "table_path is required in tables_configs"));
        String[] parts = tablePath.split("\\.", 2);
        if (parts.length != 2 || StringUtils.isBlank(parts[1])) {

View on GitHub (pinned to cf67b549a7)

Solutions

Inspect the attached cause exception (print the full stack trace) — it names the real failure
Validate the tables_configs structure: each entry must be a map with table_path and allowed options
Compare with a minimal known-good tables_configs to isolate the bad entry
Upgrade/patch the connector if the cause indicates an internal bug

Example fix

// before
tables_configs = ["Account"]  // wrong type
// after
tables_configs = [{table_path = "default.Account"}]

Defensive patterns

Strategy: validation

Validate before calling

// validate entry shape before building configs
for (Object entry : tablesConfigs) {
    if (!(entry instanceof Map) || !((Map<?,?>) entry).containsKey("table_path")) {
        throw new IllegalArgumentException("Each tables_configs entry must be a map with table_path");
    }
}

Type guard

boolean isValidEntry(Object e) {
    return e instanceof Map && ((Map<?,?>) e).get("table_path") instanceof String;
}

Try / catch

try {
    new SalesforceSource(config);
} catch (SalesforceConnectorException e) {
    if ("Failed to build Salesforce table configs".equals(e.getMessage())) {
        e.getCause().printStackTrace(); // real cause
    }
}

Prevention

Always inspect getCause() — this error is only a wrapper
Validate tables_configs structure with a JSON/config linter before running
Test configs with a minimal single-table setup first
Match connector docs exactly for option names and types

When it happens

Trigger: Any runtime exception during config building: JSON parsing of config maps, NPEs from missing fields, IO/network errors outside the typed paths, ClassCastExceptions from malformed tables_configs structure.

Common situations: Malformed tables_configs entries (wrong types, e.g. string instead of map); schema/config-deserialization bugs; unexpected client errors not wrapped by lower-level codes.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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