Connector troubleshooting in Jitterbit Studio

This guide covers errors and unexpected behavior that are specific to individual Jitterbit Studio connectors, organized by connector. It lists only connectors that have known, connector-specific issues to document, not every available connector. For the complete list of connectors, see Connectors. Start with the diagnostic steps below, then find your connector in the relevant section.

For issues that are not specific to a connector, such as an operation that will not run or a problem with a transformation, script, or function, see Operation troubleshooting. For private agent problems, such as an agent that is offline, unhealthy, or slow (which can stop operations from running at all), see private agent troubleshooting.

For a unified reference covering integration, automation, API management, EDI, and app development issues in one place, see the Harmony troubleshooting guide.

Diagnostic steps

These steps apply to most connector-related failures and are the recommended starting point before investigating a specific connector error.

Test the connection

In the connection configuration, click the Test button to confirm the connection succeeds. Clicking Test also downloads the latest version of the connector to the agent, unless the Disable Auto Connector Update organization policy is enabled.

Refresh the connection metadata and activity schemas

Many connector problems, such as missing objects, an out-of-date field list, or a schema that no longer matches the endpoint, are caused by cached metadata. After any change on the endpoint side (new fields, an API version change, or a permission change), reopen the affected activity and click the refresh icon (Refresh) to reload objects and schemas from the endpoint.

Confirm connector availability and keep it current

The Agent availability column on the Connectors list shows whether a connector requires a private agent.

Connectors are released and updated on Jitterbit's release schedule, separately from the agent. On private agents, testing a connection downloads the latest version of the connector (see Test the connection above), unless the Disable Auto Connector Update organization policy is enabled. To update the connectors for an agent group at any time, including when that policy is enabled, select Action > Update connectors for the group on the Management Console Agents page.

Enable connector verbose logging

When directed by Jitterbit support, enable connector verbose logging on the private agent to capture connector-level detail, then reproduce the issue and review the logs. Verbose logging uses a connector-specific logger entry; the exact line to add to logback.xml is given in the Troubleshooting section of that connector's own documentation page, under Connectors.

Connection configuration

Advanced Configurations Properties: Variables containing raw JSON must be escaped

• Symptom: Many connectors include an Advanced Configurations Properties table for optional connection settings. Variables used in these fields that contain raw JSON must have the JSON escaped; passing unescaped raw JSON via a variable causes the field value to be malformed.
• Possible cause: Fields in the Advanced Configurations Properties table do not support variables that carry unescaped raw JSON objects.
• Resolution:
  • Before passing JSON content via a variable into an Advanced Configurations Properties field, escape the JSON. For example, {"success": "true"} must be escaped as {\"success\": \"true\"} before it is assigned to the variable.
  • If you are entering the JSON value directly into the field (not via a variable), escaping is not required.
  • Variables in Advanced Configurations Properties fields are populated at runtime only on agent version 10.75 / 11.13 or later. If a variable value does not appear at runtime, confirm the agent meets this minimum version.

Amazon Bedrock connector

Amazon Bedrock: "on-demand throughput isn't supported" model error

• Symptom: An Amazon Bedrock activity fails with:

  Invocation of model ID <model-name> with on-demand throughput isn't supported. Retry your request with the ID or ARN of an inference profile that contains this model.
  

• Possible cause: Some models are only available in specific regions and require a region prefix on the model ID.

• Resolution:
  1. Add the region prefix to the model ID. For example, anthropic.claude-3-5-haiku-20241022-v1:0 becomes us-anthropic.claude-3-5-haiku-20241022-v1:0.
  2. Enter the prefixed model ID using the Enter model identifier option in the activity configuration.

Cloud Datastore connector

Delete Items activity reports success but does not delete the record

• Symptom: A Cloud Datastore Delete Items activity reports success in the operation log, but the target record still exists when queried afterward.
• Possible cause: Delete Items identifies records by the storage's Key (or Alternative Key) value, supplied in the request's keys or ids array. (Both arrays accept key or alternative key values.) If the record's internal ID is supplied instead of its key value, no item matches, and the activity reports success without deleting anything.
• Resolution:
  • In the transformation that prepares the Delete Items request, map the storage's Key (or Alternative Key) value, not the internal record ID.
  • When chaining from a Query Items activity, map the key value from the query response into the delete request.

Coupa connector

Coupa: API key authentication returns 403 Forbidden

• Symptom: A Coupa connector operation fails with a Forbidden (403) error when using API key authentication.
• Possible cause: As of Coupa release R35 (January 2023), Coupa API keys are deprecated and no longer supported for authentication. Connections configured to use API key authentication receive a 403 error.
• Resolution:
  1. In the Coupa connection configuration, switch from API key authentication to OAuth 2.0 authentication.
  2. In your Coupa instance, create an OAuth 2.0 client application and obtain the client credentials.
  3. Update the connection configuration with the OAuth 2.0 credentials, save, and retest.

Database connector

MySQL: ODBC driver not listed in Studio dropdown

• Symptom: When configuring a Database connection to MySQL using an ODBC driver on a private agent, the installed driver does not appear in the Driver dropdown in Studio.
• Possible cause: The ODBC manager on the private agent host is not showing the driver, usually because of a 32-bit vs. 64-bit mismatch or an incomplete driver installation.
• Resolution:
  • On the private agent host (Windows), open Data Sources (ODBC) (under Administrative Tools) and confirm the MySQL ODBC driver is listed. For MySQL driver options, see Connect to MySQL.
  • Confirm the agent is connecting to the correct machine: the ODBC driver must be installed on the agent host, not on the Studio user's machine.

MySQL: Access denied despite correct credentials

• Symptom: Connecting to a MySQL database using the Database connector fails with:

  Access denied for user 'root'@'%' to database 'test'
  

  even when the username and password are correct.

• Possible cause: MySQL can grant different permissions based on the client IP address. A user account may have the required privileges from specific IP addresses but not from the private agent's IP address.

• Resolution:

  • In MySQL, verify that the user account has the necessary grants for connections from the private agent's IP address. The exact grant syntax varies by MySQL version (see the MySQL documentation or contact your MySQL administrator), but generally takes the form:

    GRANT ALL ON database.* TO 'user'@'agent-ip';
    

  • Test connectivity using a MySQL client installed directly on the agent host to isolate whether the issue is network-based or Jitterbit-specific.

PostgreSQL: Client encoding mismatch error

• Symptom: A Database connector connection test to PostgreSQL fails with a "client encoding mismatch" error.
• Possible cause: The encoding that the PostgreSQL server uses differs from the default encoding assumed by the PostgreSQL ODBC driver.
• Resolution:
  • In the Database connection settings, add ConnSettings=SET CLIENT_ENCODING to 'LATIN1' (substituting the server's actual encoding) to the Additional Connection String Parameters field.
  • On Windows, if the server uses a Cyrillic encoding such as WIN1251, also set the client encoding to WIN1251 in the ODBC driver settings.

Database (ODBC): Multibyte characters are not handled correctly

• Symptom: When reading from or writing to a database through the Database connector using an ODBC driver, multibyte or non-ASCII characters (for example, accented or non-Latin characters) are not handled correctly.
• Possible cause: Multibyte character support for the Database connector over an ODBC driver is not enabled by default. The jitterbit.scripting.db.multibyte.enable Jitterbit variable must be set to true. This support is available on agent version 12.6 and later, and is not required when using a JDBC driver.

• Resolution:

  1. Confirm the agent is version 12.6 or later.

  2. Set the jitterbit.scripting.db.multibyte.enable variable to true before the database operation runs. For example, in a script step:

     $jitterbit.scripting.db.multibyte.enable = true;
     

  Alternatively, use a JDBC driver for the database connection, which handles multibyte characters without this variable.

PostgreSQL: Use the Jitterbit-provided driver on Linux

• Symptom: Operations using the Database connector to connect to PostgreSQL from a Linux private agent fail or produce errors, even when a driver appears to be installed.
• Possible cause: Many Linux distributions include a PostgreSQL ODBC driver packaged with unixODBC that does not work reliably with Harmony.
• Resolution: Do not use the distribution-packaged PostgreSQL driver. Use the PostgreSQL ODBC driver bundled with the Jitterbit agent installation instead.

IBM DB2 on iSeries: JDBC connection fails

• Symptom: A Database connection to IBM DB2 on iSeries (AS/400 or IBM i) using a JDBC driver fails to connect.
• Possible cause: Some connections to DB2 on iSeries using a JDBC driver encounter issues that do not occur with an ODBC driver.
• Resolution: Switch the connection to use an ODBC driver instead of JDBC. ODBC connections are supported on private agents only.

IBM DB2: JCC JDBC driver setup (deprecated JAR and license file)

• Symptom: A Database connection using the IBM DB2 JCC JDBC driver fails with an error referencing a missing license, or fails or produces compatibility errors with newer DB2 releases.
• Possible causes:
  • The driver file db2jcc.jar implements the deprecated JDBC 3 specification. The current db2jcc4.jar implements JDBC 4, which newer DB2 releases require.
  • The JCC driver requires a separate license JAR file. The driver JAR alone is not sufficient.
• Resolution:
  • Use the db2jcc4.jar driver, not the deprecated db2jcc.jar. Install it in <JITTERBIT_HOME>/tomcat/drivers/lib/ on the private agent.
  • Obtain the license JAR file from IBM (named db2jcc_license_cisuz-XX.jar, where XX is the version number) and copy it to <JITTERBIT_HOME>/tomcat/shared/lib/.
  • Alternatively, use the JTOpen open-source library (also known as the AS400 driver), which does not require the JCC driver or a license file.

Database: SQL statement exceeds 2,000-character limit

• Symptom: A Database Query activity fails or is truncated when the configured SQL statement is very long.
• Possible cause: The SQL statement field in a Database Query activity accepts a maximum of 2,000 characters.
• Resolution:
  1. Create a database view that encapsulates the complex query logic.
  2. Reference the view name in the Query activity instead of the full SQL statement.

Database (JDBC): DBLookup or DBExecute fails with a Base64 decoding error

• Symptom: A DBLookup or DBExecute function targeting a PostgreSQL or SQL Server database over a JDBC driver fails at runtime with:

  Base64 decoding failed. Reason: error:00000000:lib(0)::reason(0)
  

  This occurs whenever the returned value resembles Base64-encoded data, such as a JWT or other access token, even though the same query succeeds when run directly against the database.

• Possible cause: Versions of the agent earlier than 12.9 may incorrectly attempt to Base64-decode a JDBC result value that matches a Base64-like pattern, regardless of whether the value is actual Base64-encoded data.

• Resolution:

  • For private agents, upgrade to version 12.9 or later. Cloud agents receive the update automatically.
  • If you cannot upgrade immediately, avoid triggering the Base64 check by converting the affected value to hexadecimal in the SQL query, then decoding it in a script step using HexToString. For example, in PostgreSQL: SELECT encode(<column>, 'hex'). Use the equivalent SQL decode(...,'hex') with StringToHex when writing the value back to the database.

Database: DBLookup or DBExecute fails with "No suitable driver found" when testing a script

• Symptom: Testing a script (using Run test) that calls DBLookup or DBExecute fails with:

  No suitable driver found for [...]
  

  The same script runs successfully when deployed and executed in an operation.

• Possible cause: The Database connection used by the function has its Login, Password, or Connection String field set to a global or project variable. A script test runs only the tested script, so the variable has not yet been assigned its runtime value when the function resolves the connection. Unlike a variable referenced in an activity's own configured field, this is not covered by a variable's default value; a database function does not read the default value when resolving a connection.

• Resolution: Before the function call, temporarily assign the same global or project variable its actual value directly within the tested script (for example, $login = "value"; for a variable named login), then remove the assignment before deploying the operation.

Microsoft Excel: "Operation must use an updateable query"

• Symptom: A Database Insert or Update activity targeting a Microsoft Excel file (via ODBC) fails with:

  [Microsoft][ODBC Excel Driver] Operation must use an updateable query
  

• Possible cause: The ODBC Excel driver opens the Excel file in read-only mode by default unless the connection string explicitly sets read/write mode.

• Resolution: In the Database connection's Connection String field (entered under Optional Settings with Use Connection String selected), append ReadOnly=0; to the end of the connection string to open the Excel file in read/write mode.

SQL Server Windows authentication: Insufficient privileges

• Symptom: A Database connection using SQL Server Windows authentication fails even when the domain credentials appear correct.
• Possible cause: The Windows domain user running the Jitterbit agent service lacks the OS-level privileges required for Windows Integrated Security.
• Resolution:
  1. Grant the domain user the Log on as a service and Act as part of the operating system Windows privileges on the private agent host.
  2. Confirm the domain user has read and write permissions on the Jitterbit agent installation directory.
  3. Restart the Jitterbit agent service after applying privilege changes.

SQL Server JDBC: Windows integrated authentication fails

• Symptom: For private agents, a Database connection to SQL Server using a JDBC driver and Windows integrated authentication fails with:

  This driver is not configured for integrated authentication. ClientConnectionId:...
  

  The agent logs may also show:

  java.lang.UnsatisfiedLinkError: no mssql-jdbc_auth-8.2.0.x64 in java.library.path
  

• Possible causes:

  • The mssql-jdbc_auth DLL required for Windows integrated authentication is missing from the JRE directories that the Jitterbit agent uses at runtime. Placing the DLL in the same directory as the JDBC JAR file is not sufficient.
  • The connection string does not include the integratedSecurity=true parameter.

• Resolution:

  1. On the private agent host, copy mssql-jdbc_auth-x.x.x.x64.dll (from the JDBC driver distribution, using the version that matches the JDBC JAR file bundled with your agent) into both <JITTERBIT_HOME>/jre/bin and <JITTERBIT_HOME>/jre/lib. Back up the file, as it may be removed during major agent upgrades.
  2. In the Database connection settings, add integratedSecurity=true to the Additional Connection String Parameters field.
  3. Restart the Jitterbit agent service.

SQL Server: Connection fails with a PKIX certificate path error

• Symptom: A Database connection to SQL Server fails with:

  "encrypt" property is set to "true" and "trustServerCertificate" property is set to "false" but the driver could not establish a secure connection to SQL Server by using Secure Sockets Layer (SSL) encryption: Error: (certificate_unknown) PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target.
  

  A connection that worked previously can begin to fail after an agent upgrade to 12.8 or later.

• Possible cause: Current versions of the SQL Server MS JDBC driver request an encrypted connection by default and validate the certificate that the database server presents. The connection fails when that certificate can't be traced to a certificate authority (CA) the agent already trusts, such as a self-signed certificate, an internally issued certificate, or the Amazon RDS CA certificate that an Amazon RDS for SQL Server instance presents. This is a failure of certificate trust rather than of encryption, so a database can have encryption enabled and a valid certificate installed and still fail. Agent version 12.8 updated the bundled driver to a version that requests encryption by default, so a connection configured before that upgrade can fail afterward.

• Resolution: Enter encrypt=false; in the Additional Connection String Parameters field under Optional Settings of the Database connection, or include it in a manual connection string. This works on cloud and private agents. For more information, see Connection encryption and server certificates.

  Caution

  With encrypt=false, data travels between the agent and the database unencrypted. Use this option only where that is acceptable for the data and the network path involved.

Kerberos: "Could not initialize class KerbAuthentication"

• Symptom: A Database connection using Kerberos authentication fails with:

  Could not initialize class com.microsoft.sqlserver.jdbc.KerbAuthentication
  

• Possible cause: The Kerberos configuration files on the agent host do not have the correct file permissions.

• Resolution:

  1. On the private agent host, set file permissions on the Kerberos configuration files (jaas.conf, krb5.conf, and the Kerberos ticket cache file) to 644:

     chmod 644 jaas.conf krb5.conf krb5cc_agent
     

  2. Restart the agent after applying permission changes.

Kerberos: JGSS or GSS errors during connection test

• Symptom: A Database connection using Kerberos authentication fails with errors referencing jgss or gss.
• Possible cause: The JVM is configured with -Dsun.security.jgss.native=true, which directs it to use the OS native GSSAPI library. On some systems, this conflicts with the Kerberos configuration.
• Resolution:
  1. Remove the -Dsun.security.jgss.native=true parameter from the agent's JVM arguments.
  2. In krb5.conf, add udp_preference_limit = 1 under the [libdefaults] section to force TCP instead of UDP for Kerberos traffic.
  3. Restart the agent.

Database: JDBC driver JAR overwritten on agent upgrades

• Symptom: Custom JDBC driver JAR files installed for the Database connector are deleted or overwritten when the agent is upgraded.
• Possible cause: Only the <JITTERBIT_HOME>/tomcat/drivers/lib/ directory is preserved across agent upgrades. Custom driver JAR files placed elsewhere in the agent's directories are part of the managed deployment and can be removed or overwritten during an upgrade.
• Resolution:
  • Place custom JDBC driver JAR files in <JITTERBIT_HOME>/tomcat/drivers/lib/ instead. This directory is preserved during agent upgrades.
  • If drivers are currently in the wrong location, move them to the correct directory and restart the agent.

Database: Special characters in column names cause query failures

• Symptom: Database queries or transformations fail when a source table has column names that contain special characters such as @.
• Possible cause: ODBC drivers cannot handle certain special characters in database column names.
• Resolution:
  1. Create a database view on the physical table that exposes the affected column under a name that does not contain special characters.
  2. Point the Database activity to the view rather than the original table.

SQL Server: "Cannot insert explicit value for identity column" when inserting into an identity column

• Symptom: A Database connector operation that writes to a SQL Server table with an identity column fails with:

  Database Error: Cannot insert explicit value for identity column in table '<table>' when IDENTITY_INSERT is set to OFF.
  

• Possible cause: The identity column is included in the INSERT statement that the Database connector generates for the target. SQL Server rejects an INSERT that references an identity column in its column list (with an explicit value, or a null) while IDENTITY_INSERT is set to OFF. Mapping the field to a null value does not exclude it: a target field is omitted from the INSERT only when it is mapped with the Unmap function.

• Resolution:

  • To let SQL Server assign the identity value automatically, exclude the column from the INSERT by mapping the identity target field with the Unmap function. To exclude the column only when the source provides no value, use a conditional mapping:

    If($source.id != "", $source.id, Unmap())
    

    When the condition is false, Unmap removes the column from the INSERT and SQL Server assigns the next identity value. (Supplying an explicit value in the true branch still requires IDENTITY_INSERT to be ON; see the next option.)

  • If you must insert explicit values into the identity column, set IDENTITY_INSERT on the target table in pre- and post-SQL scripts within the activity:

    SET IDENTITY_INSERT <table> ON;
    

    SET IDENTITY_INSERT <table> OFF;
    

    Use this option only when you intentionally want to control identity values from outside the database. It allows explicit values to be inserted into the identity column.

Database: Field length errors on Insert, Update, or Upsert

• Symptom: A Database Insert, Update, or Upsert activity fails with an Error operation status when a mapped source value is longer than the target column allows. The operation log contains one of:

  One or more values were truncated when inserting and/or updating the field
  

  Field value too long
  FieldName: m_site  Length: 3  Length Allowed: 1
  

• Possible cause: By default, if a mapped source value exceeds the target column's defined length, the activity rejects the row and reports an Error status rather than truncating the value.

• Resolution:
  1. In the Database Insert, Update, or Upsert activity configuration, enable Allow truncation of character fields to avoid field length errors. With this option enabled, values that exceed the target field length are truncated and the operation reports a Success with Info status instead of an Error status.
  2. If truncation is not acceptable, trim or transform the source field in the transformation mapping so values never exceed the target column length, or widen the target column on the database side.
  3. Redeploy and rerun the operation.

EDI for Cloud v2 connector

Troubleshooting entries for the EDI for Cloud v2 connector are documented in the EDI troubleshooting guide, alongside Jitterbit EDI issues. Relevant entries include:

• EDI for Cloud v2 activity fails on a private agent behind a firewall or proxy
• Transformation error: Unrecognized field in EDI for Cloud v2 activity
• Repeating EDI segment or loop maps only the last iteration
• Adding nested hierarchical loop (HL) levels to an EDI transformation

Email connector

Gmail connection test fails with authentication error

• Symptom: A connection test to a Gmail account using Basic Auth fails with an authentication error, even when the correct Google account password is entered.
• Possible cause: Google requires an app password for accounts with 2-Step Verification enabled. The Google account password is not accepted by SMTP or IMAP when 2-Step Verification is active; only app passwords are.
• Resolution:
  1. In your Google account, generate an app password for the Jitterbit application (see Google's Sign in with app passwords page).
  2. In the Email connection configuration in Studio, enter the app password in the SMTP Password and/or IMAP Password field instead of the Google account password.

S/MIME signing fails or is rejected by cloud email providers

• Symptom: Emails configured with S/MIME signing fail to send, are rejected by the recipient's server, or arrive unsigned when using a cloud email provider such as Microsoft 365 or Exchange Online.
• Possible causes:
  • Cloud providers require an S/MIME certificate issued by a trusted certificate authority (CA). Self-signed certificates are not accepted by cloud providers such as Microsoft 365 (Exchange Online).
  • S/MIME is functional only when using private agents. If the operation runs on a cloud agent, S/MIME signing does not apply regardless of the certificate type.
• Resolution:
  1. Obtain an S/MIME certificate from a trusted CA. Let's Encrypt provides free certificates accepted by major cloud providers.
  2. Replace the self-signed certificate in the Email Send Email activity with the CA-issued certificate (see Prerequisites for S/MIME encryption).
  3. For private agents, confirm that the certificate is correctly imported into the agent's default truststore. For cloud agents, S/MIME signing is not supported.

Microsoft 365 Email connection using ROPC authentication fails when MFA is enabled

• Symptom: A Microsoft 365 OAuth 2.0 connection that uses the Resource Owner Password Credentials (ROPC) grant fails to authenticate, even when the username, password, client ID, tenant ID, and client secret are all correct.
• Possible cause: ROPC authentication requires multi-factor authentication (MFA) to be disabled for the Microsoft 365 credentials used with the connector. The ROPC grant cannot satisfy an MFA challenge, so the token request fails when an MFA policy applies to the account.
• Resolution:
  • Use a Microsoft 365 account whose credentials are not subject to an MFA policy. To maintain security, create a dedicated Microsoft Entra ID tenant or directory that does not enforce MFA, as described in Prerequisites for Microsoft 365.
  • If MFA cannot be removed from the account, use a different supported authentication method for the connection rather than ROPC.

Send Email fails when the same address appears in multiple recipient fields

• Symptom: An Email Send Email activity fails at runtime when the same email address is present in more than one of the To, CC, or BCC fields.
• Possible cause: The Email connector does not permit the same address to appear in multiple recipient fields in a single send request. This applies to addresses configured directly in the activity and to addresses supplied dynamically through a transformation mapping.
• Resolution:
  • Review the To, CC, and BCC fields in the activity configuration and in any transformation mapping for the activity to confirm no address appears in more than one field.
  • If recipient lists are assembled dynamically using variables or scripts, add a deduplication check before passing addresses to the activity.

Epicor connectors

Epicor Prophet 21: Operation fails at runtime with multiple filter conditions

• Symptom: An Epicor Prophet 21 Query activity fails at runtime when the Filter String contains more than one filter condition, even though the activity appears valid in Studio.
• Possible cause: A limitation in the Epicor Prophet 21 Middleware API prevents multiple filter conditions from being processed. The operation appears valid in Studio but fails at runtime when more than one filter is present.
• Resolution:
  • Reduce the Filter String to a single filter condition.
  • If multiple filter conditions are needed, retrieve a broader result set using a single filter and apply the additional filtering in a transformation or script step after the activity.

File connectors

FTP, File Share, and Local Storage: "No files match the file filter" on archive or follow-up steps

• Symptom: An FTP, File Share, or Local Storage read activity fails because the file it expects to read is no longer at the source path:

  Failed to read file from the source "Read". Reason: No files match the file filter "<filter>".
  

  The activity that previously processed the file succeeded; the failure is on a later step (often an archive or notification step) that tries to read the same file with the same filter.

• Possible causes:

  • The processing activity already moved or deleted the source file as part of its After Processing behavior, so the archive step has nothing left to match.
  • A child operation is launched asynchronously and the parent operation attempts to read the child's output file before the child has finished writing it.
  • An FTP Write activity with Use FTP Rename enabled (the default) writes the file under a temporary name and renames it to the final name on completion. A downstream read operation that fires before the rename completes will not find the file.
• Resolution:
  • Confirm whether the prior step already handled archival via its built-in After Processing options (move, rename, delete). If so, a separate archive step is redundant and should be removed.
  • If a separate archive step is required, redesign the chain so that processing and archival happen against the same in-memory file reference rather than re-reading from the source. For example, pass the read content through Temporary Storage to the archive step instead of re-reading the source path.
  • If a follow-up step reads output produced by a child operation, run the child synchronously so its output exists before the read. Set the Invoke Operation tool's Run type to Synchronously, or, when calling the operation from a script, run RunOperation synchronously (the default). Inserting a fixed delay (for example, with the Sleep function) adds latency and does not guarantee the file is ready.
  • If an FTP Write activity is writing to the same location, check whether Use FTP Rename is enabled on the FTP Write activity. If the downstream read is firing before the rename completes, disable Use FTP Rename on the write activity, or ensure the read operation does not run until the write operation has fully completed.

FTP, File Share, and Local Storage: Error folder not written on connection failure

• Symptom: After an FTP, File Share, or Local Storage activity fails, no file appears in the configured error folder.
• Possible cause: The error folder is designed to archive a copy of the source file after unsuccessful processing, so it captures files only when the activity runs and then fails (for example, a write permission error on the server). If the connection to the server cannot be established at all, the operation fails before the activity reads any file, so there is no file to write to the error folder.
• Resolution:
  • If the error folder is empty after a failure, check the operation logs for a connection-level error (such as an authentication failure or host unreachable message).
  • Use the Test button on the connection to confirm whether the issue is at the network or authentication level.

FTP, File Share, and Local Storage: Filename keywords not resolved in success and error folder paths

• Symptom: Operations move files to success or error folders after processing, but the destination path includes unexpanded keyword text rather than resolved values. The operation may fail or write files to unexpected locations.
• Possible causes:
  • The success folder and error folder path fields in FTP, File Share, and Local Storage activities do not support filename keyword substitution. Variables are not expanded in these fields.
  • These fields refer to directories on the private agent machine, not on the remote server. Relative paths are interpreted relative to the agent host's file system.
• Resolution:
  • Use only literal paths (without filename keyword variables) for the success and error folder fields.
  • If dynamic paths are required, add a script step after the activity to move or rename the processed file to the intended location using file functions.

FTP, File Share, Local Storage, and Temporary Storage: Write Headers does not produce a header-only file when the source returns no records

• Symptom: A file-based write activity with the Write Headers option enabled (FTP Write, File Share Write, Local Storage Write, or Temporary Storage Write) does not write headers when the source returns no records. Either an empty file is created or no file is created at all (if Do not create empty files is also selected).
• Cause: This is expected behavior. Headers are written as part of the transformation output, and the transformation runs only when the source returns at least one record. When the source returns no records, the transformation is skipped, so no output (including headers) is written, and Studio logs a warning that the source is empty. This is not specific to a particular source connector or flat file target.

FTP: Operation fails after many rapid logins to the same server

• Symptom: An operation using the FTP connector (over either the FTP or SFTP protocol) that authenticates to the same server many times in quick succession (for example, reading hundreds of small files inside a loop, or many operations running against the same server on a schedule) eventually fails with a login denial or connection error. The same operation succeeds under lighter load.
• Possible causes:
  • The FTP connector opens and authenticates a new connection for each activity execution and closes it when the operation ends; a session is not reused across activities, across operation runs, or across projects. This is by design. When many operations run against the same server, for example several scheduled operations or multiple projects targeting the same host, each run authenticates independently.
  • The remote server is configured with a maximum number of connections, authentications per minute, or concurrent sessions per user, and the combined Jitterbit login rate exceeds that limit.
• Resolution:
  • Where possible, redesign the operation to make fewer connections. Replace a Read activity inside a loop with a single Read activity that uses a wildcard in the Get Files field (for example, *.xml or data_*.csv), then split the retrieved data into individual records inside a transformation.
  • If the operation must process files one at a time, ask the FTP server administrator to raise the per-user limit on concurrent connections or authentications per minute.

SFTP "Login denied. Authentication failure." when using SSH keys

• Symptom: An SFTP operation using SSH private-key authentication fails with Login denied. Authentication failure., even though the same keys authenticate successfully from an interactive SFTP client.

  Failed to get ftp directory list for url sftp://example.com:22/. Login denied. Authentication failure.
  

• Possible causes:

  • The private key is protected by a passphrase, but the PrivateKeyPassphrase setting is missing from the agent's jitterbit.conf [SSH] section.
  • A password is configured in the FTP endpoint along with the private key. The presence of a password in the endpoint settings interferes with key-based authentication.

• Resolution:

  • For private agents, confirm that the [SSH] section of jitterbit.conf contains the correct PrivateKeyFile path and, if the key is passphrase-protected, the matching PrivateKeyPassphrase value (see Connecting to SFTP with SSH keys).
  • In the FTP endpoint configuration, clear the Password field when authentication is by SSH key.
  • Confirm the key is in a format the agent supports (OpenSSH). Convert the key with ssh-keygen if it is in PuTTY (.ppk) or another non-OpenSSH format.

FTP Write: "Use FTP Rename" fails when writing to an SFTP server

• Symptom: An FTP Write activity configured with the Use FTP Rename option fails when the target is an SFTP server, with an error similar to:

  Failed to put ... to the url ...
  Quote command returned error. Rename command failed: <reason>.
  

  The <reason> is typically No such file or directory, or Permission denied for a file whose name contains multibyte characters.

• Possible causes:

  • On agents earlier than 11.56, the Use FTP Rename option did not reliably honor the rename step when writing to an SFTP server, particularly in archive pattern operations.

  • The file name contains multibyte characters and the SFTP server does not support renaming files whose names contain them. As of agent version 12.8, the FTP connector can read and write files with multibyte names; however, with Use FTP Rename the agent uploads the file under a temporary name (a -jbupload suffix) and then renames it to the final name, and if the server cannot rename the multibyte name it returns a misleading Permission denied. File names using only ASCII characters are unaffected. This is a limitation of the SFTP server, not of Jitterbit.

• Resolution:

  • Ensure the agent is version 11.56 or later, where Use FTP Rename with SFTP works as expected. Cloud agents are updated automatically; upgrade private agents if needed.

  • Clear the Use FTP Rename checkbox in the activity configuration so the agent writes directly to the destination path instead of uploading to a temporary name and renaming. This avoids the rename step and resolves both causes.

  • For the multibyte case, alternatively use an SFTP server that supports renaming files whose names contain multibyte characters.

SFTP: Append to file not supported

• Symptom: An FTP Write activity configured with the Append To File option does not append to the existing file when the target is an SFTP server.
• Possible cause: The SFTP protocol does not support appending to existing files. This is a protocol-level limitation, not a Jitterbit configuration issue.
• Resolution:
  • Use FTP or FTPS if the append behavior is required.
  • If SFTP is required, implement append logic manually: read the existing file content, combine it with the new data, and write the complete result back as a full file.

FTP: Filenames containing # are not handled correctly

• Symptom: An FTP connector activity (over either the FTP or SFTP protocol) fails when the source or target filename contains a hash (#) character. Reading the file returns an error such as No File with that name or Error in SSH Layer, and writing the file produces a truncated filename.
• Possible cause: The FTP connector treats the file path as a URL, in which the hash character is a reserved fragment delimiter. The connector parses the part of the path before the # and discards the rest.
• Resolution:
  • Rename the files to remove or replace the # character before Jitterbit reads or writes them.
  • To have the connector URL-encode names that contain special characters such as #, set jitterbit.source.ftp.encode_url to true in a transformation script for source file or folder names, and jitterbit.target.ftp.encode_url to true for files written to the target.

File Share: UNC paths with server names fail on cloud agents

• Symptom: File Share connections that use UNC paths (for example, \\server\share) fail to connect when the operation runs on a cloud agent.
• Possible cause: Cloud agents can resolve UNC paths using a public IP address but cannot resolve server hostnames in UNC paths.
• Resolution:
  • Replace the server name in the UNC path with the server's public IP address (for example, \\192.0.2.1\share).
  • If server-name resolution in UNC paths is required, use a private agent instead.

File Share: Files larger than 2 GB may fail to retrieve

• Symptom: A File Share Read activity may fail to retrieve individual files larger than 2 GB. Smaller files are retrieved without issue.
• Possible cause: The File Share connector has a known limitation with individual files larger than 2 GB.
• Resolution: No configuration option removes this limit. As a workaround, split the file into smaller segments at the source so that each file is under 2 GB before the File Share Read activity retrieves it.

Local Storage: Not available on cloud agents

• Symptom: An operation using a Local Storage connector fails when it runs on a cloud agent.
• Possible cause: Local Storage accesses the file system on the machine where the agent is installed. Cloud agents run in a hosted environment and do not expose a local file system for this purpose.
• Resolution:
  • Use private agents for any operations that require the Local Storage connector. Local Storage is disabled on private agents by default, so also enable it in the private agent configuration file (see Enable local file location).
  • For cloud agent workflows, replace Local Storage with Temporary Storage or an external storage connector (File Share, FTP, or Cloud Datastore).

Temporary Storage: Files missing when read by a later operation

• Symptom: Temporary Storage files written by one operation are missing when a later operation attempts to read them.
• Possible causes:
  • Harmony's cleanup service deletes files from Temporary Storage after 24 hours by default.
  • Each agent in an agent group has its own local Temporary Storage. Operations in the same operation chain are guaranteed to run on the same agent, but a later operation that is not in the same chain may be dispatched to a different agent and access a different Temporary Storage instance, so it does not find the file, regardless of the 24-hour window. See Important notes.
• Resolution:
  • Link operations that must share Temporary Storage files into the same operation chain using operation actions, where Temporary Storage behavior is consistent and reliable.
  • For private agents, the cleanup frequency can be adjusted in the [FileCleanup] section of jitterbit.conf. See [FileCleanup].
  • If files cannot be consumed within the same chain or must persist longer than 24 hours, use a persistent storage connector accessible to all agents (such as File Share, FTP, or Cloud Datastore) instead of Temporary Storage.

Temporary Storage: Restricted characters in file paths

• Symptom: A Temporary Storage Read or Write activity fails when the file path contains certain special characters.
• Possible cause: The following characters are not supported in Temporary Storage file paths: ~, %, $, ", <, >, :, ?
• Resolution:
  • Remove or replace the unsupported characters in the file path. The following characters are supported: !, @, #, ^, &, *, (, ), [, ], ', ;
  • Both / and \ are accepted as path separators.

Temporary Storage: 50 GB file size limit on cloud agents

• Symptom: A Temporary Storage Write activity fails when writing large files through a cloud agent.
• Possible cause: Cloud agents impose a maximum file size of 50 GB per file for Temporary Storage.
• Resolution:
  • Use a private agent for workflows that need to write individual files larger than 50 GB to Temporary Storage.
  • If only cloud agents are available, split large data sets into multiple files smaller than 50 GB before writing to Temporary Storage.

HTTP connector

HTTP v2: Duplicate Authorization header causes 400 Bad Request

• Symptom: HTTP v2 connector operations fail with a 400 error when both connection-level authentication and a manually defined Authorization request header are configured on the same connection or activity.
• Possible cause: When authentication is configured on an HTTP v2 connection (for example, Basic or OAuth), the connector automatically adds an Authorization header to each request. Adding a second Authorization header manually results in two conflicting headers, which most servers reject with a 400 error.
• Resolution:
  • Remove any manually added Authorization header from the request headers in the activity or connection configuration.
  • Use only the built-in authentication settings in the connection to handle authorization. Do not add a manual Authorization header alongside configured authentication.
  • If you need to set the Authorization header dynamically at the activity level, set the connection's authentication type to No Auth and configure the activity's Authorization request header as needed.

HTTP v2: JSON value in a request-header project variable fails to parse

• Symptom: An HTTP v2 activity that reads a request header value from a project variable containing a JSON string fails with a parse error:

  Expected a ',' or ']' at 139 [character 140 line 1]
  

  The same JSON works when pasted directly into the Value column of the Request Headers table.

• Possible cause: When a request-header value is read from a project variable, the HTTP v2 connector does not escape the embedded quotes the way it does when you type the value directly into the Request Headers table. The unescaped quotes break the header string before it reaches the target.

• Resolution:
  • When storing JSON in a project variable that will be used as a header value, escape each double quote with a backslash. For example, store the value as {\"success\": \"true\"} rather than {"success": "true"}.
  • If the JSON content is static, paste it directly into the Value column of the Request Headers table instead of using a variable. The connector applies the necessary escaping in that path.

HTTP and HTTP v2: URL contains multiple ? characters

• Symptom: An HTTP or HTTP v2 operation fails at the target system. The agent logs show that the request URL contains more than one ? between segments, for example https://api.example.com/endpoint?param1=A?param2=B.
• Possible cause: Query parameters were declared in two places: appended directly to the URL path and also added to the activity's Request Parameters table. The connector concatenates both sets, inserting a second ? instead of a &.
• Resolution:
  • Remove any query string segment from the URL path. The base URL should contain only the path itself (for example, https://api.example.com/endpoint).
  • Define every query parameter in the activity's Request Parameters table. The connector inserts the ? and & characters automatically when constructing the final URL.

HTTP v2: Double URL encoding when "Encode request URL" is enabled

• Symptom: REST API calls made through the HTTP v2 connector fail at the target system because URL parameters appear double-encoded in the outbound request (for example, a %20 space becomes %2520).
• Possible cause: When Encode request URL is enabled in the HTTP v2 connection settings, the connector encodes the entire URL before sending it. If URL parameters already contain percent-encoded characters, those characters are encoded a second time.
• Resolution:
  • Disable Encode request URL in the HTTP v2 connection settings when the URL or parameters are already encoded or constructed using the URLEncode function.
  • If Encode request URL must remain enabled, ensure that parameters passed into the URL are not pre-encoded before they reach the connection.

HTTP v2: Operation fails when Base URL redirects

• Symptom: An HTTP v2 operation fails immediately when the configured Base URL returns a redirect response (3xx).
• Possible cause: Follow redirects is disabled in the HTTP v2 connection settings, so redirect responses are treated as failures rather than being followed automatically.
• Resolution: In the HTTP v2 connection settings, enable Follow redirects to allow the connector to automatically follow redirect responses to the final target URL.

HTTP v2: Variables in the activity Path are not resolved

• Symptom: An HTTP v2 activity uses a global, project, or Jitterbit variable in its Path field, but at runtime the variable is sent literally (unresolved) instead of being replaced with its value.
• Possible cause: A full URL (one that includes the protocol and host, such as https://api.example.com/...) was entered in the Path field. Variables are not supported in full URLs. They are only resolved in a partial path that is appended to the connection's Base URL.
• Resolution:
  1. In the HTTP v2 connection, set the Base URL to the protocol and host portion of the endpoint (for example, https://api.example.com).
  2. In the activity Path field, enter only the partial path that follows the base URL, and place the variable within that partial path (for example, /records/[recordId]). The connector resolves the variable and appends the result to the Base URL at runtime.

HTTP v2: Response status code not available in Jitterbit variables

• Symptom: Scripts that read Jitterbit source or target variables to capture the HTTP response status code after an HTTP v2 activity runs receive no value. The same approach works with the HTTP connector but not with HTTP v2.
• Possible cause: The HTTP v2 connector does not populate Jitterbit source or target variables. Response data, including the HTTP status code, is returned through the activity's response schema instead.
• Resolution:
  • To capture the status code using the default response schema, map the statusCode field, which is located under the response's responseItem/error node and holds the HTTP status code (for example, 200, 403). For details on the response schema structure, see the activity configuration documentation for any HTTP v2 activity.
  • To capture the status code when using a custom response schema, enable Include Additional Properties from HTTP Response in the Schema in the activity configuration. This wraps the schema with a Jitterbit-defined structure that includes __jitterbit_api_statuscode__ (the status code) and __jitterbit_api_errorbody__ (the response body for unsuccessful requests).
  • For the status code to be available when the API returns a non-successful response, enable Ignore operation error in case of non-successful status code in the activity's optional settings. Without this setting, the operation fails on non-successful responses before the response data can be mapped.

HTTP v2: XML namespaces rewritten when using a custom request schema

• Symptom: An HTTP v2 operation that sends an XML payload to a SOAP or XML web service fails with a server error (such as 500 Internal Server Error) even though the same payload succeeds when sent from Postman or SoapUI. Inspecting the request body received by the target shows that XML namespace declarations have been consolidated onto the root element and the original namespace prefixes have been replaced with generic ones (for example, soapenv:Envelope becomes Envelope xmlns="...", and element prefixes are renumbered as ns, ns1, ns2).
• Possible cause: When a custom request schema is used in HTTP v2 activity configuration, the transformation normalizes the XML by default, moving all namespace declarations to the root node and reassigning their prefixes. SOAP services and other XML endpoints that validate namespace prefix consistency reject the modified payload.

• Resolution:

  • On agent version 12.8 or later, set jitterbit.target.xml.preserve.namespace.prefix to true in a script step upstream of the transformation, to keep the source XML's namespace prefixes instead of reassigning generic ones:

    $jitterbit.target.xml.preserve.namespace.prefix = true;
    

  • If your private agents are earlier than 12.8, or the target also rejects the consolidation of namespace declarations onto the root element, use the default request schema instead of a custom one and map the complete XML payload as a string into the schema's body field. The payload is then treated as a string rather than parsed XML, so its namespace declarations are preserved. The response schema can still be a custom schema.

HTTP v2: Spaces encoded as + instead of %20

• Symptom: REST API calls using the HTTP v2 connector fail at the target system because spaces in the URL are encoded as + rather than %20, causing the target to return a resource not found error.
• Resolution:
  • In the HTTP v2 connection, enable the Encode request URL option. The connector then URL-encodes the request URL, encoding spaces as %20.
  • Provide the request URL completely unencoded. Do not pre-encode characters or apply the URLEncode function to the URL, because already-encoded characters become double-encoded when Encode request URL is enabled (for example, example+string%20value becomes example%20string%2520value).

HTTP: Sends null as the string "null"

• Symptom: An HTTP POST or PUT activity sends fields mapped with the Null function as the string "null" (or omits them) rather than emitting a JSON null literal. This occurs when the request schema is defined on the activity.
• Possible cause: When the request schema is defined on the HTTP activity, the connector does not serialize a mapped Null as a JSON null. When the schema is defined in the transformation instead, with no request schema provided on the activity, the connector sends a mapped Null as a JSON null correctly.
• Resolution:
  • Migrate the activity to the HTTP v2 connector, which serializes Null correctly. Jitterbit recommends converting existing HTTP connections and activities to HTTP v2.
  • If the activity must remain on HTTP, define the request schema in the transformation rather than on the activity, and leave the activity's request schema unset. With the schema defined in the transformation, the connector serializes a mapped Null to a JSON null correctly.

LDAP connector

LDAP Delete Entry fails when the target entry has child entries

• Symptom: An LDAP Delete Entry activity fails with an error from the LDAP server (for example, notAllowedOnNonLeaf or a message indicating the entry is not a leaf node).
• Possible cause: The LDAP protocol does not permit deleting an entry that has child entries (subordinates). The entry must be a leaf node with no children for deletion to succeed.
• Resolution:
  • Before deleting the parent entry, delete all child entries first. Traverse the hierarchy from the deepest entries upward.
  • If deleting an entire subtree is required, implement a script that identifies and deletes entries from the bottom of the tree upward, using RunOperation with the LDAP Delete Entry activity for each entry.

LDAP Search Entry: Filter expression is case-sensitive on some servers

• Symptom: An LDAP Search Entry activity returns no results or an error, even though the queried entries exist in the directory.
• Possible cause: Some LDAP servers require attribute names in filter expressions to match the exact case used by that server's schema. The filter expression pre-populated by Studio uses title case for the structural class (for example, ObjectClass), but some servers require a different case (for example, objectClass).
• Resolution:
  1. In the LDAP Search Entry activity configuration, review the pre-populated Filter Expression field.
  2. Adjust the case of attribute names to match what the target LDAP server expects. For example, change ObjectClass to objectClass if the server requires lowercase.
  3. Consult your LDAP server's documentation or schema definition for the required attribute naming conventions.

Microsoft connectors

Microsoft SharePoint Online: SOAP schema connections failing after IDCRL retirement

• Symptom: Operations using a Microsoft SharePoint Server connector with the SOAP schema connection type have started failing or returning authentication errors when connecting to SharePoint Online.
• Possible cause: Microsoft retired the IDCRL (Identity Client Runtime Library) method used by SOAP schema connections to SharePoint Online. After May 1, 2026, operations using the SharePoint SOAP schema for SharePoint Online connections are expected to fail.
• Resolution:
  1. In Studio, open each affected SharePoint connection and change the Schema setting from SOAP to REST.
  2. Reconfigure any activities that used the SOAP schema to use equivalent REST operations.
  3. Test and redeploy the affected operations.
  4. For migration details, see the Microsoft SharePoint Server connector documentation.

Microsoft Dynamics 365 Business Central v2: Type names incompatible with metadata

• Symptom: Operations using the Microsoft Dynamics 365 Business Central v2 connector fail with errors indicating that type names in the payload are incompatible with the OData metadata.
• Possible cause: Certain Dynamics 365 Business Central OData API endpoints require OData type annotations on the request payload. By default the connector does not include these annotations, which causes type incompatibility errors for those endpoints.
• Resolution:
  1. Open the Microsoft Dynamics 365 Business Central v2 Update activity configuration.
  2. In Optional settings, enable Set OData type on payload.
  3. Save the activity and retest the affected operations.

Microsoft Entra ID: Extension attributes not selectable as query filter conditions

• Symptom: When configuring a Microsoft Entra ID Query activity, the onPremisesExtensionAttributes field and its child extension attribute fields (for example, extensionAttribute1 through extensionAttribute15) do not appear in the Object Fields picker in step 3 and cannot be selected as conditional clause filter conditions.
• Possible cause: onPremisesExtensionAttributes is a complex-type (nested) object. The step 3 Object Fields picker exposes only primitive data type fields; complex-type fields are excluded from the selection list.
• Resolution: The onPremisesExtensionAttributes fields do not need to be selected in step 3 to be returned. They appear in the activity's output schema in step 4 and are populated at runtime when the operation runs. To access extension attribute values, map from onPremisesExtensionAttributes and its child fields in the transformation.

Microsoft Entra ID Update activity: DateTime fields rejected with Edm.String type mismatch

• Symptom: A Microsoft Entra ID Update activity fails with:

  A value was encountered that has a type name that is incompatible with the metadata.
  The value specified its type as 'Edm.String', but the type specified in the metadata is 'Edm.DateTimeOffset'.
  [HTTP/1.1 400 Bad Request]
  

• Possible cause: The connector sends DateTime field values (such as employeeHireDate) without the @odata.type annotation required by the Microsoft Graph API. Without the annotation, the value is interpreted as Edm.String instead of Edm.DateTimeOffset, causing a 400 error.

• Resolution:
  1. Open the Microsoft Entra ID Update activity configuration.
  2. In step 1, expand Optional settings and enable Set OData type on payload.
  3. Save the activity, redeploy, and rerun the operation.

Microsoft Entra ID Query: "Unsupported or invalid query filter clause" on filtered properties

• Symptom: A Microsoft Entra ID Query activity fails when a filter condition is applied in step 3:

  (Request_UnsupportedQuery) Unsupported or invalid query filter clause specified for property '<property>' of resource '<object>'. [HTTP/1.1 400 Bad Request]
  

  The same query succeeds when no filter is applied.

• Possible cause: Filtering on certain Microsoft Entra ID properties (such as companyName and createdDateTime) uses the Microsoft Graph API's advanced query capability, which requires $count=true in the query string. Without it, the API rejects the filter even when the syntax is otherwise correct. The connector automatically includes the required ConsistencyLevel: eventual header, but $count=true must be added separately.

• Resolution: Choose one of the following options depending on the tab used in step 3:
  • Basic tab: Select the Include Count checkbox. This adds $count=true to the query automatically.

  • Advanced tab: Append &$count=true to the filter string manually. For example:

    $filter=companyName eq 'Example Corp'&$count=true
    

For the list of properties that require advanced query syntax, see Advanced query capabilities on Microsoft Entra ID objects in the Microsoft Graph documentation.

Microsoft Dynamics AX 2012 operations fail with "Logon failed"

• Symptom: Operations using the Microsoft Dynamics AX connector against AX 2012 fail at runtime, even though the connection test passes in Studio. The Jitterbit Dynamics AX 2012 Connector REST Service log contains:

  The server has rejected the client credentials.
  

  The logon attempt failed
  

• Cause: The Domain Name field in the AX 2012 connection is not set to the correct value. AX 2012 authentication requires the Domain Name to be the DNS domain name extension (for example, yourcompany.com), not a short or NetBIOS domain name. An incorrect domain value causes AX to reject otherwise-valid credentials with a logon failure, even when the connection test succeeds.

• Resolution:
  1. Open the Dynamics AX 2012 connection in Studio.
  2. Set the Domain Name field to your DNS domain name extension (for example, yourcompany.com), not a short/NetBIOS domain name.
  3. Confirm the Login is the AX service account username with the required privileges, and re-enter the Password to rule out a stale value.
  4. Test the connection, then re-run the operation.

NetSuite connector

NetSuite Create, Update, or Upsert fails with "is not a legal value for Country"

• Symptom: A NetSuite Create, Update, or Upsert activity fails when the source value for a country field does not match a NetSuite Country enum value:

  FaultString: org.xml.sax.SAXException: <country_value> is not a legal value for {urn:types.common_<version>.platform.webservices.netsuite.com}Country
  

• Possible cause: The NetSuite SuiteTalk API requires Country (and other enumerated fields) to be one of the WSDL's predefined enum values (for example, _unitedStates). A country display name, an ISO country code, or any value that does not exactly match the WSDL enum is rejected.

• Resolution:
  • In the transformation that maps to the NetSuite target, translate the source country value to the matching NetSuite enum value before writing. A cross-reference dictionary, a Case statement, or a lookup table all work for this.
  • Build the cross-reference from the Country enum defined in the NetSuite SuiteTalk WSDL your connector is using. The valid values change between WSDL versions, so always check against the WSDL version currently configured on the connection.
  • Apply the same approach to any other field backed by a NetSuite enum (for example, State, Currency) where source values do not already match the WSDL enum.

OData connector

OData v2 entity sets fail to load with "No entity sets found"

• Symptom: Configuring an OData Query activity that points at an OData v2.0 service returns an error when fetching the object list, even though the connection test succeeds:

  An error occurred while fetching the data:
  Error while generating for query activity object list. The Exception is No entity sets found for the address provided.
  

• Possible cause: Support for OData V2 services was added to the OData connector in agent version 11.59, through the OData version connection setting. On agents earlier than 11.59 the connector supports only OData V4, so a connection pointed at an OData V2 service cannot populate the object list. The same failure occurs on 11.59 or later if OData version is left at V4 for an OData V2 service.

• Resolution:
  1. For private agents, upgrade to version 11.59 or later. Cloud agents receive the update automatically.
  2. In the OData connection, set OData version to V2 (the default is V4). Save and retest the connection.
  3. Reopen the OData Query activity. The entity sets should now load.

OData: Microsoft Dynamics 365 returns only the default company's data

• Symptom: An OData connection to a Microsoft Dynamics 365 Finance and Operations endpoint returns data for only the user's default company, so records from other companies are missing from the results.
• Possible cause: By default, a Dynamics 365 Finance and Operations OData endpoint returns only the data that belongs to the user's default company. To give the connection a cross-company (expanded) scope, a cross-company filter clause must be appended to the connection's OData metadata URL (the $metadata URL). On the metadata URL, ?cross-company=true on its own does not apply the expanded scope.

• Resolution: In the OData connection, append a dataAreaId filter clause to the OData metadata URL, replacing usrt with your data area identifier, then save and retest:

  ?$filter=dataAreaId eq 'usrt'&cross-company=true
  

  For background on how Dynamics 365 scopes OData data by company, see Microsoft's cross-company behavior documentation.

Oracle connectors

Oracle EBS: "custom provider JAR file is not present" connection error

• Symptom: Connecting to an Oracle E-Business Suite (EBS) instance fails with:

  Error connecting to Oracle EBS instance. Error is: The custom provider JAR file is not present in the Jitterbit Private Agent or it is not in the right location ($JITTERBIT_HOME/Connectors/Providers)
  

• Possible cause: The Oracle EBS connector requires the Oracle JDBC driver (ojdbc8.jar) to be placed on the private agent manually. This file is not bundled with the agent and must be added before the connection can succeed.

• Resolution:
  1. Download ojdbc8.jar from Oracle's website (an Oracle account is required).
  2. Place ojdbc8.jar in the $JITTERBIT_HOME/Connectors/Providers/ directory on the private agent host.
  3. Restart all agents in the agent group.
  4. Retest the Oracle EBS connection.

Salesforce connectors

Salesforce Events: Events cannot be enabled after agent restart

• Symptom: After a private agent is restarted or reinstalled, Salesforce Events connector events fail to enable, even when the connection credentials are correct.
• Possible cause: After a restart, the connector JAR file may not yet be present on the agent. Enabling an event requires the connector to be downloaded to the agent first.
• Resolution:
  1. Open the Salesforce Events connection configuration in Studio.
  2. Click Test to test the connection. This forces the connector JAR to be downloaded to the agent.
  3. After the connection test succeeds, attempt to enable the event again.

Salesforce Events: Listening activity limitations

The following behaviors of Salesforce Events listening activities (Subscribe Event and the Subscribe Insert, Update, and Delete CDC Event activities) are expected and do not indicate a connector defect:

• Events cannot be enabled because the maximum number of subscribers is reached. The Salesforce instance limits the number of concurrent clients (subscribers). When that limit is reached, no further events can be enabled. Reduce the number of active subscribers connected to the instance.
• Measurement symbols such as $ and % are missing from the response. These symbols are not returned, by design of the Salesforce API.
• Unmodified fields are returned as null in Change Data Capture (CDC) responses. For CDC activities, only changed fields are populated; unmodified fields are returned as null, by design of the Salesforce API.

SAP connector

Multiple SAP activities in one operation fail at runtime

• Symptom: An operation that contains more than one SAP activity, or that combines an SAP activity with a NetSuite, Salesforce, Salesforce Service Cloud, ServiceMax, or SOAP activity, deploys without any validation error but fails when run.
• Possible cause: Operations mixing these activity types appear valid in Studio and can be deployed successfully, but these combinations are not supported at runtime. The operation validation rules do not flag this pattern as an error at design time. This is a documented Studio known issue.
• Resolution:
  • Design each operation to contain only a single SAP activity, with no other SAP, NetSuite, Salesforce, Salesforce Service Cloud, ServiceMax, or SOAP activities in the same operation.
  • If data from multiple systems is needed in a single workflow, split the logic across separate operations and chain them using operation actions.

SAP RFC: "No RFC authorization for function module BAPI_TRANSACTION_COMMIT"

• Symptom: An SAP RFC activity fails at runtime with:

  JCoException occurred No RFC authorization for function module BAPI_TRANSACTION_COMMIT
  

• Possible causes:

  • The SAP user account in the connection does not have S_RFC authorization for BAPI_TRANSACTION_COMMIT or its related function groups.
  • The BAPI_TRANSACTION_COMMIT function module is not configured as remote-enabled in the SAP system.
  • The request transformation preceding the activity does not set the commit control field.

• Resolution:

  • In the SAP system, confirm that the BAPI_TRANSACTION_COMMIT function module is remote-enabled.
  • In the request transformation that precedes the SAP RFC activity, set the BAPI_COMMIT field to true.
  • Verify that the SAP user account referenced in the connection has S_RFC authorization for BAPI_TRANSACTION_COMMIT and all related function groups.
  • If the issue persists, contact your SAP BASIS administrator to review the user's authorization object assignments.

SAP connection fails with "Invalid language key"

• Symptom: An SAP connection fails during initialization with an error about the language key:

  Connector Error: AdapterResourceException: Error while creating Destination. 00024Invalid language key when configuring the text environment.
  

• Possible cause: The Language code configured in the SAP endpoint is not valid for the target SAP system: the code is not installed or supported on that system, or it is mistyped or incorrectly cased (for example, en instead of EN). SAP rejects the invalid key when initializing the destination's text environment.

• Resolution:
  1. Edit the SAP endpoint in Studio and set the Language field to a supported two-letter language code (for example, EN for English).
  2. Verify the value matches a language installed and active on the target SAP system. If unsure, confirm the integration user's default language in the SAP user profile and use that.
  3. Test the connection from Studio to confirm initialization succeeds before redeploying the operation.

ServiceNow connector

Initial operation runs are slow after agent restart or on cloud agents

• Symptom: Operations using the ServiceNow connector run slowly in two scenarios:

  • On private agents, the first operation after the agent restarts can take several minutes; subsequent runs are fast.
  • On cloud agents, runs are intermittently slow, taking minutes whenever the connector's metadata cache refreshes.

  This can cause downstream API timeouts.

• Possible cause: The connector caches ServiceNow metadata aggressively. After an agent restart on a private agent (or on every run for a cloud agent that did not preserve the cache), the first operation must rebuild the cache, which takes several minutes.

• Resolution:
  • On a private agent, mitigate the post-restart slowness by adding getcolumnsmetadata=onUse to the ServiceNow endpoint's Advanced Options. This setting is only effective on private agents.
  • For consistent performance on cloud agents, call the ServiceNow REST API through the HTTP v2 connector instead of using the ServiceNow connector. The HTTP v2 connector does not cache metadata and avoids the rebuild delay.

Shopify connector

Shopify: Activity object selections may change after API version update

• Symptom: After changing the API version on a Shopify connection, one or more Shopify activities return errors or behave unexpectedly, and a configured object or sub-object appears to have changed.
• Possible cause: Shopify releases new API versions quarterly and deprecates older versions after 12 months. When you change to a different API version, objects or sub-objects that are not available in the new version may no longer be selectable, causing the activity's configured selection to change when the configuration is refreshed.
• Resolution:
  1. After changing the Shopify API version in the connection, open each affected Shopify activity configuration.
  2. Click Refresh to reload the available objects for the new API version.
  3. Review the object and sub-object selections to confirm they reflect your intent under the new version.
  4. Update any selections that changed to the correct replacement objects.
  5. Redeploy and retest the affected operations.
  6. For information about Shopify API version deprecation timelines, see Shopify's change log.

Snowflake connector

Snowflake: Password-based connections failing after authentication deprecation

• Symptom: Operations connecting to Snowflake using the Password (Deprecated) authentication type have started failing after working previously.
• Possible cause: Snowflake is phasing out single-factor (password-only) authentication. Password-based connections fail unless the Snowflake user account's TYPE property is set to LEGACY_SERVICE.

• Resolution: Choose one of the following options:

  • Temporary workaround: In Snowflake, set the user account's TYPE property to LEGACY_SERVICE to restore password-based connectivity:

    ALTER USER <username> SET TYPE = LEGACY_SERVICE;
    

    This workaround is not a long-term solution, as Snowflake may remove support for LEGACY_SERVICE in a future release.

  • Recommended migration: Update the Snowflake connector connection in Studio to use OAuth or Key-Pair authentication, and configure the Snowflake user account to match.

Snowflake: Developer instance is sleeping, metadata tables not populating

• Symptom: When configuring a Snowflake activity, the available objects list does not populate or appears empty, even though the connection test succeeds.
• Possible cause: Snowflake Developer Instances enter a sleep state when they have not been accessed recently. While the connection test may succeed against a sleeping instance, the instance may not return table and object metadata.
• Resolution:
  1. Log in to the Snowflake web UI to wake the instance.
  2. Reopen the Snowflake connection in Studio and click Test to retest the credentials.
  3. Reopen the activity configuration to refresh the available objects list.

Snowflake Query: Flat schema root node case mismatch causes ProcessFlatStream error

• Symptom: A Snowflake Query activity using a flat schema fails at runtime with:

  StartElement() error, starting element does not match with the root.
  qName= "<table_name_lowercase>", root name="<TABLE_NAME_UPPERCASE>"
  
  ProcessFlatStream error
  

  This error occurs when the query includes a WHERE clause, a LIMIT clause, or a variable reference in a WHERE clause.

• Possible cause: The Snowflake connector returns the table name as lowercase in the XML response. When Studio generates a flat schema from the query, the root node name is created in uppercase. The case mismatch between the schema root node (uppercase) and the XML response root node (lowercase) causes the flat stream processing to fail.

• Resolution: Choose one of the following options:
  • In the flat schema, change the root node name to lowercase to match the connector output. For example, rename SALES_ORDERS to sales_orders.
  • Use the mirror schema with default mapping instead of a manually constructed flat schema. The mirror schema derives its structure directly from the connector response and does not have this case mismatch.

Snowflake Merge: stageName and fileContent are missing from the request schema for external stages

• Symptom: A Snowflake Merge activity configured against an external stage shows a request schema without the stageName and fileContent fields. The same activity configured against an internal stage exposes both fields.
• Possible cause: External stages are read-only references to files that already exist in external cloud storage (S3, GCS, or Azure Blob). The Merge activity cannot upload file content into an external stage, so the schema omits the fields that drive that upload.
• Resolution:
  • When the activity targets an external stage, ensure the data files are already present in the cloud storage location that the stage references. The Merge activity reads from those files directly; no fileContent field is needed.
  • When you do need to push file content from the operation, configure the Merge activity to use an internal stage. The schema then exposes stageName and fileContent.

Snowflake Insert or Merge: SQL syntax errors from special characters

• Symptom: A Snowflake Insert or Merge activity fails with a SQL compilation error such as:

  SQL compilation error:
  syntax error line 1 at position <n> unexpected '<token>'.
  

  Column values may also appear mis-mapped, with data from one field appearing in the wrong column.

• Possible causes:

  • Field values containing single quotes (for example, a value such as corner's) are not escaped before being included in the SQL payload. The unescaped quote terminates the string prematurely, causing the remainder of the value to be interpreted as SQL syntax rather than data.
  • A target column name contains a special character, such as a hyphen (for example, Zip-Code). Snowflake requires an identifier containing a special character to be quoted; unquoted, it produces a syntax error at the hyphen.

• Resolution:

  • For values containing single quotes: In the Snowflake connection Optional settings, enable Escape special characters. This automatically escapes single quotes in Insert and Invoke Stored Procedure activity payloads. For Merge activities, or as an alternative for Insert, use SQLEscape in the transformation mapping to escape single quotes in affected field values before they reach the activity.
  • For column names containing special characters: Confirm Use quote for Snowflake identifiers is enabled on the connection (enabled by default).

Snowflake: Java heap space error when querying large datasets

• Symptom: A Snowflake Query activity fails with the following error when the query returns a large number of rows:

  Error executing query activity. Exception is Java heap space
  

  The connector reports the error in this form because it wraps the underlying Java error, which appears further down in the stack trace:

  Caused by: java.lang.OutOfMemoryError: Java heap space
  

  If this error occurs on queries that return few rows, or the same agent also fails with heap errors through other connectors, the cause is more likely the agent's overall heap allocation than the size of the result set. See Java heap space: OutOfMemoryError.

• Possible cause: The Snowflake connector loads the entire query result set into JVM memory before passing it to the transformation. With very large result sets, this exhausts the Tomcat JVM heap on the private agent.

• Resolution: For large query volumes, use the Database connector with a Snowflake JDBC driver instead of the Snowflake connector. The Database connector does not buffer the full result set in memory, so it can handle much larger query volumes. Install the Snowflake JDBC driver on the private agent, then configure a Database connection that uses it. On agent 12.x and later, that Database connection also needs jdbc_query_result_format=json in its connection string; see Snowflake (JDBC): Operations fail after upgrading the agent to 12.x.

  If you need to stay on the Snowflake connector, either of the following can reduce memory pressure, though neither is guaranteed to be sufficient for datasets in the millions of rows:

  • Split the query into batches using SQL LIMIT and OFFSET clauses, running the operation repeatedly with incrementing offsets until all rows are processed.
  • Increase the Tomcat JVM heap size on the private agent (see Tomcat heap memory).

Snowflake (JDBC): Operations fail after upgrading the agent to 12.x

• Symptom: After upgrading a private agent to version 12.x, operations that query Snowflake through a Snowflake JDBC driver (a Database connection or a DBExecute script) fail at runtime, even though the connection test succeeds. The error references the driver's Arrow memory layer:

  JDBC driver internal error: exception creating result java.lang.ExceptionInInitializerError at net.snowflake.client.jdbc.internal.apache.arrow.memory.unsafe.UnsafeAllocationManager
  

• Possible cause: By default, the Snowflake JDBC driver returns query results in the Apache Arrow format, which is not compatible with agent 12.x and later. The driver fails when it builds the result set, so the connection test (which returns no result set) still passes while queries fail. Upgrading the JDBC driver version does not resolve it.

• Resolution: Add jdbc_query_result_format=json to the Snowflake connection string so the driver returns results in JSON instead of Arrow. Append it to the existing connection string parameters (for example, &jdbc_query_result_format=json), then save, retest the connection, and rerun the operation.

SOAP connector

SOAP deployment error: "No WSDL with locator"

• Symptom: Deploying a project that includes a SOAP connection, or an API SOAP Request or SOAP Response activity, fails with:

  Failed to deploy - Internal Error: No WSDL with locator
  

• Possible causes:

  • The WSDL was removed, re-imported, or its internal reference was broken, so the project references a WSDL identifier that no longer exists.

  • The project was deployed, or transferred to another environment, before the Harmony 12.9 release, when deploying a project could delete WSDL files that were still in use. The 12.9 release prevents the deletion, but a WSDL deleted before then must still be re-uploaded.

• Resolution:

  1. Re-upload the WSDL for the affected component:

     • For a SOAP connection, open the connection and select Upload URL or Upload file (not Select existing), re-upload the WSDL, review the Port and Select methods settings, then click Save Changes.
     • For an API SOAP Request or SOAP Response activity, open the activity and re-upload the WSDL on step 1 of its configuration.

  2. Review any transformations that inherit schemas from the re-uploaded WSDL and regenerate them if needed.

  3. Redeploy the project.

  4. If the project has multiple WSDLs and it is not clear which one is affected, see SOAP connection troubleshooting to identify it from a JSON export.

SOAP WSDL: schemaLocation must use relative references

• Symptom: A SOAP connection that references a WSDL with imported XSD schema files fails to load or produces schema resolution errors at design time.
• Possible cause: The WSDL uses absolute URLs in its schemaLocation attributes for imported XSD files (for example, http://example.com/schema.xsd). The agent cannot fetch schemas from absolute remote URLs when loading a locally imported WSDL.
• Resolution:
  1. Edit the WSDL so that all schemaLocation references use relative paths (for example, schema.xsd rather than http://example.com/schema.xsd).
  2. Place all referenced XSD files in the same directory as the WSDL and re-import the WSDL in the SOAP connection.

SOAP connector rewrites XML namespace prefixes and structure

• Symptom: The XML envelope produced by a SOAP activity does not match the literal namespace prefixes or structure of the source WSDL (for example, the connector substitutes xmlns:ns1 for xmlns:glob). Strict SOAP services that compare the exact prefix text reject the request.
• Possible cause: The transformation engine processes SOAP messages as structured XML, not as literal text. It produces a semantically equivalent payload that may use different namespace prefixes than the source WSDL.
• Resolution: For SOAP services that require a literal XML structure, bypass the SOAP connector and build the request payload as a string:
  1. Create an HTTP v2 connection pointing to the SOAP service URL.
  2. In a transformation, build the SOAP envelope as a string, concatenating string literals and mapped values with the + operator. Alternatively, read a template from a file and substitute dynamic values with Replace.
  3. In the HTTP v2 POST activity, use the default request schema (do not upload a custom request schema) and map the constructed SOAP envelope string to the body field of that schema. The connector sends the body value as-is, preserving the literal XML.
  4. Set the Content-Type header to text/xml or application/soap+xml, and set the SOAPAction header if the service requires it.
  5. Read the service's response from the responseContent field of the activity's default response schema.

SOAP: MTOM/XOP messages are not supported

• Symptom: The SOAP connector does not support SOAP MTOM/XOP (Message Transmission Optimization Mechanism) messages.
• Resolution: Use the workaround in Support SOAP MTOM/XOP messages using Jitterbit Studio, which builds the MTOM request outside the SOAP connector.

VTEX connector

Connection test fails with "You don't have permission to access this resource"

• Symptom: A VTEX connection test fails with a permission error in Studio even though the same credentials work in external tools such as Postman.

  You don't have permission to access this resource
  

• Possible cause: The VTEX user or application key associated with the connection is missing one or more permissions that the connector uses to validate the connection. These permissions are stricter than those needed for basic data access.

• Resolution:
  1. In the VTEX admin portal, open the access profile assigned to the user or application key Jitterbit is using.
  2. Confirm the access profile includes the License Manager feature with access to the Get account by identifier resource.
  3. Save the profile and retest the VTEX connection in Studio.

Workday connector

Workday: WSDL v42.0 and v42.1 return errors for specific services

• Symptom: Operations using the Workday connector configured with WSDL version 42.0 or 42.1 fail when accessing the Human_Resources or Resource_Management web services.
• Possible cause: WSDL v42.0 is known to return errors for the Human_Resources (v42.0) and Resource_Management (v42.0) services. WSDL v42.1 is known to return errors for the Human_Resources (v42.1) service. These are known issues specific to those WSDL versions.
• Resolution:
  1. In the Workday connection configuration, change the WSDL version to 41.x or 43.0 or later for operations that use the Human_Resources or Resource_Management services.
  2. Test the connection and rerun the affected operations to confirm the issue is resolved.

Workday: Connection test fails with "The task submitted is not authorized"

• Symptom: A Workday connection test fails with:

  Error occurred while opening connection. The Exception is Processing error occurred. The task submitted is not authorized.
  

  This error can occur with both Basic Auth and JWT Bearer authentication types. Note that operations may run successfully at runtime even when the connection test returns this error, because the test calls a specific Workday service (Get_Message_Template_Translation_Request) that requires a permission the ISU may not have, while the actual integration operations call different services.

• Possible causes:

  • The Integration System User (ISU) has not been assigned to the Setup Administrator security group in Workday. The connector's test connection call is rejected if the ISU lacks this security group membership.
  • The Workday Host field contains an incorrect value. An incorrect host causes the connection to fail before authentication is attempted.

• Resolution:

  1. Verify that the Workday Host value in the connection configuration is correct. The host should be the base URL of your Workday tenant (for example, https://wd5-impl-services1.workday.com/). You can confirm the correct value from the Workday View API Client page.
  2. In the Workday instance, open the Assign Users to User-based Security Group task, select Setup Administrator, and confirm the ISU is listed under System Users. If not, add the ISU. For full steps, see Prerequisites.
  3. Confirm that the Configure Web Service Security task has also been completed for the ISU, as described in the Prerequisites page.
  4. Retest the connection.