Salesforce connector troubleshooting in Jitterbit Studio

Overview

This topic provides troubleshooting information specific to the Salesforce connector. It may also apply to the Salesforce Service Cloud and ServiceMax connectors.

Testing and logging

If you experience issues with the Salesforce connector, these troubleshooting steps are recommended:

1. Ensure the Salesforce connection is successful by using the Test button in the configuration screen. If the connection is not successful, the error returned may provide an indication as to the problem.

2. Check the operation logs for any information written during execution of the operation.

3. Enable operation debug logging (for cloud agents or for private agents) to generate additional log files and data.

4. If using private agents, you can check the agent logs for more information.

5. For additional troubleshooting considerations, see Operation troubleshooting.

Record limits and chunking

Operations fail due to Salesforce API record limits

• Symptom: A Salesforce standard activity (such as Upsert) fails or processes fewer records than expected because the source data exceeds the per-call record limit. The operation may fail with:

  EXCEEDED_ID_LIMIT: record limit reached. cannot submit more than 200 records into this call
  

• Cause: Standard Salesforce activities accept a maximum of 200 records per call. When more records are sent in a single call, Salesforce rejects the excess. This can happen when chunking is not enabled, or when chunking is enabled but not honored because the source is a Connector SDK-based connector such as HTTP v2. Chunking is not supported on SDK-based sources, so all records are sent in a single call regardless of the configured chunk size (see Chunking not honored when the source is an SDK-based connector).

• Resolution:

  • Enable chunking on the operation and set the chunk size to 200 or fewer. For instructions, see Enable Chunking.
  • Confirm the chunk size is actually applied to the source data. When the source is a large payload produced by another activity, verify that the operation splits it into calls of 200 records or fewer. If the limit is still exceeded despite a correct chunk size, contact Jitterbit support.
  • For Salesforce bulk activities, increase the default chunk size of 200 to a larger value such as 10,000, as bulk activities are designed to handle high record volumes.

  Chunking splits the data during transformation rather than at retrieval. When the source is a Salesforce activity, each chunk is written to a temporary file and the files are combined into the final target after all chunks are processed. When the target is a Salesforce activity, each source chunk produces one target chunk, with the transformation applied separately to each, and the resulting target chunks are then combined. For more detail, see Detailed chunking information.

Authentication errors

Multi-factor authentication prevents basic-authentication connections

• Symptom: A connection that uses Basic Auth with the Salesforce, Salesforce Service Cloud, or ServiceMax connector fails its connection test, or connects but fails operations with an authentication error.
• Cause: These connectors share the same code base and authenticate to a Salesforce org. Basic authentication requires a Salesforce account whose assigned permission set does not include the Multi-Factor Authentication for API Logins permission. When that permission is assigned (MFA active for the account), basic authentication connections fail.
• Resolution:
  • In Salesforce, review the permission set assigned to the system integration login user and confirm that Multi-Factor Authentication for API Logins is not selected. System integration login types are exempt from Salesforce's MFA requirement. For details, see Salesforce's Multi-Factor Authentication FAQ.
  • If MFA cannot be removed from the integration user, switch the connection to 2-legged OAuth 2.0 authentication.

Certificate Subject Alternative Name (SAN) mismatch

• Symptom: A Salesforce connection to a sandbox or an org with Enhanced Domains enabled fails with:

  Certificate for <url> doesn't match any of the subject alternative names
  

• Possible causes:

  • The certificate does not include the Salesforce MyDomain or sandbox URL in its Subject Alternative Names.
  • The Sandbox checkbox in the Salesforce connection settings is not correctly toggled.

• Resolution:

  • Inspect the certificate's SAN entries using OpenSSL: openssl x509 -in cert.crt -text -noout. Confirm the Subject Alternative Name section includes your Salesforce MyDomain URL.
  • In the Salesforce connection settings in Studio, verify the Sandbox checkbox is correctly set for your target org.
  • If the Salesforce URL is absent from the SANs, regenerate the certificate to include the specific domain.
  • If the same connection succeeds on a cloud agent group but fails on a private agent, the cause may instead be a missing SNI extension in the agent's TLS handshake. See Salesforce sandbox connection fails with certificate mismatch.

Activity configuration errors

Data schema does not include recently added Salesforce fields

• Symptom: A field recently added to a Salesforce object does not appear in the transformation schema when configuring a Salesforce activity.
• Cause: The data schema is cached from when the activity was last configured and is not refreshed automatically.
• Resolution: Open the activity configuration and advance through each step. Make at least one minor change (such as adding and removing a character from the activity name) to force a schema reload. Click Finished to save the updated configuration.

Automap does not map fields when a Salesforce activity is the transformation target

• Symptom: When a Salesforce activity (such as Insert or Upsert) is used as the target of a transformation, using Automap does not map any fields.
• Cause: The Salesforce activity schema includes an extra root node above the object fields when the schema is mirrored. This extra root node prevents automap from matching source fields to the correct target fields.
• Resolution:
  1. In the transformation canvas, locate the top-level object node on the target side (for example, Account).
  2. Drag the corresponding source node to align with it manually.
  3. With the nodes aligned, run Automap again. Fields under the node will be mapped automatically.

Query activity: Parent-child query generates hierarchical schema

• Symptom: A Salesforce Query activity using a parent-child SOQL query generates a hierarchical response schema. When this schema is mirrored on the target side of a transformation, the output is hierarchical XML rather than a flat structure.
• Cause: The hierarchical schema reflects the parent-child relationship in the query. Mirroring the source schema on the transformation target preserves that hierarchy in the output.
• Resolution:
  • To produce flat output, define a flat schema on the target side of the transformation rather than mirroring the source schema.
  • If accessing query results in a script, the data is already available as a flat structure without any additional configuration.

Data write errors

Upsert fails for some records: Duplicate external ID

• Symptom: A Salesforce Upsert or Bulk Upsert operation completes but reports failures for some records.
• Cause: Multiple source records share the same external ID value. When the external ID is not unique, Salesforce returns an error and the upsert fails for those records.
• Resolution:
  • Check the failure file in the Management Console Runtime page (Activity Logs tab) to identify which records failed.
  • Ensure the field used as the external ID has a unique value for each record. See Create a Salesforce external ID for Jitterbit.

Insert or Update activity: Record ID field cannot be mapped

• Symptom: A transformation includes a mapping to the Salesforce record ID field in an Insert or Update activity, but the operation does not use the mapped value.
• Cause: The Salesforce record ID field cannot contain a mapping in Insert and Update activities. Salesforce assigns the record ID automatically on insert; the Update activity identifies records by their existing Salesforce ID, which is not a mappable target field.
• Resolution: Remove the mapping to the record ID field from the transformation. If the goal is to update a specific record by its Salesforce ID, verify that the source data provides that ID and that the Update activity is configured to match records against it.

Bulk write activities: First data record skipped when source has no header row

• Symptom: A Salesforce bulk write activity (Bulk Insert, Bulk Upsert, Bulk Update, Bulk Delete, or Bulk Hard Delete) runs without error but fewer records than expected are written to Salesforce. When the source contains only one data record, no records are written at all.
• Cause: Salesforce bulk write activities always treat the first row of source data as the column header row. This behavior cannot be changed. If the source file does not include a dedicated header row, the first data record is consumed as the header and is not written to Salesforce.
• Resolution:
  • Ensure the source data includes a header row as the first row. The header values must match the column names defined in the activity's field mapping.
  • Verify that data rows begin on the second row, immediately after the header.

Bulk activity operation steps show as "Incomplete" with no input or output data

• Symptom: When viewing an operation log that includes a Salesforce bulk activity (Bulk Insert, Bulk Upsert, Bulk Update, Bulk Delete, or Bulk Hard Delete), the bulk activity's operation step entry shows a status of Incomplete and displays no input or output data, even when the operation completed successfully and records were processed.
• Cause: Salesforce bulk activities do not generate component input and output data in the operation log. The Incomplete status on the activity step and the absence of input and output data are expected behavior for all bulk activities, regardless of whether processing succeeded.
• Resolution:
  • To determine whether records were processed and whether any errors occurred, check the text entries in the operation log for error messages or confirmation of successful processing.
  • For private agents, you can also download detailed per-record results: in the Management Console, go to the Runtime page, select the execution, open the Activity Logs tab, and download the results file.

Bulk activities fail when triggered by an API or SOAP request

• Symptom: A Salesforce bulk activity (Bulk Query, Bulk Update, Bulk Insert, Bulk Upsert, Bulk Delete, or Bulk Hard Delete) fails immediately at initialization with:

  Failed to initialize the operation: Failed to get the operation with OperationID = [ID].
  A database exception occurred. The reported error was:
  ERROR: null value in column "organization_id" of relation "bulkloadinstancetab" violates not-null constraint
  

  The same bulk activity runs without issue when triggered independently or through other means.

• Possible cause: Operations triggered via an API or SOAP request (such as a Salesforce outbound message flow) do not support Salesforce bulk activities. In this context, the organization ID is not available to the bulk load subsystem, causing the database constraint failure at initialization.

• Resolution: Replace the bulk activity with the equivalent standard Salesforce activity in operations that are part of an API- or SOAP-triggered chain. For example, replace a Bulk Query with a standard Query activity, or a Bulk Update with a standard Update activity. Standard activities work correctly in this context.