apache/seatunnel · error · SalesforceConnectorException

DESCRIBE_OBJECT_FAILED

DESCRIBE_OBJECT_FAILED

Error message

HTTP " + status + " describing " + objectName + ": " + body

What it means

Thrown by SalesforceClient.describeObject when the Salesforce REST API /sobjects/{object}/describe call returns a non-200 status. The message embeds the HTTP status, the object name, and the raw response body so the actual Salesforce cause (auth failure, missing object, etc.) is visible. It wraps any failure of the describe request into the connector's DESCRIBE_OBJECT_FAILED error code.

Source

Thrown at seatunnel-connectors-v2/connector-salesforce/src/main/java/org/apache/seatunnel/connectors/seatunnel/salesforce/client/SalesforceClient.java:137

        } catch (SalesforceConnectorException e) {
            throw e;
        } catch (Exception e) {
            throw new SalesforceConnectorException(SalesforceConnectorErrorCode.AUTH_FAILED, e);
        }
    }

    public CatalogTable describeObject(String database, String objectName) {
        String url =
                authorizedInstanceUrl
                        + String.format(DESCRIBE_PATH, params.getApiVersion(), objectName);
        HttpGet get = new HttpGet(url);
        get.setHeader(HttpHeaders.AUTHORIZATION, "Bearer " + accessToken);

        try (CloseableHttpResponse response = httpClient.execute(get)) {
            int status = response.getStatusLine().getStatusCode();
            String body = EntityUtils.toString(response.getEntity(), StandardCharsets.UTF_8);
            if (status != 200) {
                throw new SalesforceConnectorException(
                        SalesforceConnectorErrorCode.DESCRIBE_OBJECT_FAILED,
                        "HTTP " + status + " describing " + objectName + ": " + body);
            }
            return buildCatalogTable(database, objectName, objectMapper.readTree(body));
        } catch (SalesforceConnectorException e) {
            throw e;
        } catch (Exception e) {
            throw new SalesforceConnectorException(
                    SalesforceConnectorErrorCode.DESCRIBE_OBJECT_FAILED, e);
        }
    }

    private CatalogTable buildCatalogTable(String database, String objectName, JsonNode describe) {
        TableSchema.Builder schemaBuilder = TableSchema.builder();
        for (JsonNode field : describe.get("fields")) {
            String name = field.get("name").asText();
            String sfType = field.get("type").asText();
            SeaTunnelDataType<?> seaType = mapSalesforceType(sfType);

View on GitHub (pinned to cf67b549a7)

Solutions

1. Read the embedded HTTP status and body in the message to identify the Salesforce cause
2. Verify the object name in table_path matches a real Salesforce object (case-insensitive API name, e.g. Account)
3. Re-authenticate: check the token endpoint / credentials so the Bearer token is valid at request time
4. Grant the integration user API access and View permission on the object in the Salesforce profile/permission set

Example fix

// before
table_path = "default.Accouts"  // typo
// after
table_path = "default.Accounts"

// validate object exists before connecting
// curl -H "Authorization: Bearer $TOKEN" \
//   https://<instance>/services/data/vXX.0/sobjects/Account/describe
// expect HTTP 200 before running the job

boolean isObjectNameValid(String name) {
    return name != null && name.matches("[A-Za-z][A-Za-z0-9_]*");
}

try {
    client.describeObject(database, objectName);
} catch (SalesforceConnectorException e) {
    if (e.getMessage().contains("HTTP 401")) {
        refreshTokenAndRetry();
    } else {
        throw new IllegalArgumentException("Invalid Salesforce object: " + objectName, e);
    }
}

When it happens

Trigger: Calling describeObject for an object name that does not exist (400/404), an expired or invalid access token (401/403), or any Salesforce-side error during the GET describe request.

Common situations: Typo in the table_path object name in tables_configs; insufficient API access on the connected app; Salesforce org returned INVALID_SESSION_ID because the access token expired between login and describe; the object is not queryable for the integration user.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

• REQUEST_FAILED
• Failed to execute HTTP request to %s , http status code is %
• REST_SERVICE_FAILED
• Failed to get response from Doris
• AUTH_FAILED

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