Design Studio troubleshooting

This guide covers common errors and issues encountered when using Jitterbit Design Studio. Start with the diagnostic steps below, then find your specific issue in the relevant section.

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

For issues with the private agent running your Design Studio operations, see private agent troubleshooting. For errors that occur when operations run, the operation troubleshooting guide covers Studio rather than Design Studio, but many of the entries (for example, stuck operations, script errors, and connection failures) are applicable to Design Studio operations as well.

Diagnostic steps

Check the error log

Design Studio displays system errors in a built-in error pane. Select Error Log from the View menu to open it. Each error appears as a separate entry with a description. To save the error details for a support case, click Save in the upper-right corner of the error pane.

Check the known issues page

Review the Design Studio known issues page for issues that have been identified with recent versions of Design Studio.

Login and connection failures

SSL certificate or proxy filter setting error

• Symptom: Design Studio displays an SSL certificate or proxy filter error when attempting to log in.
• Possible causes:
  • A signed SSL or CA certificate used by your network (for example, from a web filter, proxy, or VPN) is not present in the Jitterbit Java KeyStore.
  • The IP allowlist for your network proxy or web filter does not include the required Jitterbit addresses. See Allowlist information.
• Resolution: For full resolution steps, including how to add certificates to the Jitterbit Java KeyStore, see SSL certificate or proxy filter setting error.

SSO users outside the organization's region cannot log in

• Symptom: After Harmony single sign-on (SSO) is enabled for the organization, users whose Harmony region is different from the default region the Design Studio login dialog connects to cannot complete the SSO sign-in. Users in the default region log in without issue.
• Possible cause: Design Studio defaults to a single Harmony region URL at the login dialog. When SSO is enabled, the SSO redirect resolves only against the Harmony region that hosts the organization, so users must point Design Studio at that region's URL before signing in.
• Resolution:
  • At the Design Studio login dialog, press Ctrl + Shift + U to open the URL field. Enter the URL for the organization's Harmony region (for example, https://na-east.jitterbit.com for NA or https://emea-west.jitterbit.com for EMEA), then complete the SSO sign-in.
  • To make the change persistent, set the URL in the client.properties configuration file:
    • Open <Jitterbit Studio Home>\configuration\client.properties in a text editor (on macOS, the path is /Applications/Jitterbit Studio [version].app/Contents/Java/configuration/client.properties).
    • Uncomment the cloud.url parameter and set it to the regional URL.
    • Save the file and relaunch Design Studio.

Installation and startup

macOS: "Client Properties Do Not Exist" error on launch

• Symptom: Design Studio fails to launch on macOS with an error indicating that client properties do not exist.
• Possible cause: Design Studio was launched directly from the disk image (.dmg) rather than from the Applications folder. The application must be copied to the Applications folder before it can locate its configuration files.
• Resolution:
  1. Quit Design Studio if it is running.
  2. Open the .dmg installer file.
  3. Drag the Jitterbit Studio icon into the Applications folder shortcut in the installer window.
  4. Launch Design Studio from the Applications folder (or from Spotlight/Launchpad), not from the disk image.

Design Studio flagged as malicious software on macOS Sequoia

• Symptom: On macOS 15 (Sequoia), macOS displays a warning that Design Studio is malicious software and prevents it from opening.
• Possible cause: macOS Gatekeeper warns about applications that are not notarized by Apple and are distributed outside the Mac App Store. Because Design Studio is distributed from the Harmony portal Downloads page, macOS reports that it cannot check it for malicious software. This is standard macOS behavior, not an actual problem with the installer.
• Resolution:
  1. Confirm Design Studio was downloaded from the official Harmony portal Downloads page.
  2. If you see the malicious software warning for an installation downloaded from the portal, the warning can be dismissed: it does not indicate an actual security risk with the Jitterbit installer.

Display issues

Blurry or small UI on Windows 10 high-density displays

• Symptom: Design Studio elements appear blurry or too small when running on Windows 10 with a high-DPI display such as a 4K monitor.
• Possible cause: A default Windows 10 DPI scaling setting that is not compatible with Design Studio.
• Resolution: For resolution steps, see Windows 10 high-density display scaling error.

Performance

Long project load time when using a proxy

• Symptom: Opening a Design Studio project takes more than several minutes when connecting through a proxy. This may be accompanied by an error such as:

  Message: Unable to load image icon at this address: https://citizen.jitterbit.eu/v1/endpoints/s3images/financialforce.png
  Details: Can't get input stream from URL!
  

• Possible cause: The delay is typically caused by Design Studio attempting to fetch Citizen Integrator recipe icons through a proxy that cannot reach the external image server.

• Resolution: For resolution steps, see Long load times when using a proxy.

Transformations

Transformation with a script fails with /PRESCRIPT/ node error

• Symptom: A transformation that uses a script fails at runtime with:

  Can not find target node (/PRESCRIPT/).
  The structure may have changed so try to open the transformation 'example' and refresh the structure trees.
  

• Possible cause: The internal XML structure of the transformation has become inconsistent with the current target schema, typically after a schema change.

• Resolution:
  1. Open the failing transformation in Design Studio.
  2. On the Target side, click the refresh button at the top of the structure tree. This rereads the schema and rebuilds the transformation's internal structure.
  3. Save and deploy the transformation.

Unmap does not unmap a field when used together with RunScript

• Symptom: A target field's mapping expression involves both RunScript and Unmap, but the field is not unmapped. For a JSON or XML target, the field appears in the output with a null value instead of being omitted.

• Possible causes:

  • RunScript precedes Unmap in the same mapping expression (for example, RunScript("<TAG>script:MyScript</TAG>"); Unmap();). On agent versions earlier than 12.9, this combination did not unmap the field.
  • Unmap is called from inside the script invoked by RunScript, rather than directly in the target field's own mapping expression. RunScript returns the called script's result as a string rather than propagating an unmap signal back to the mapping, so calling Unmap from inside the called script has no effect, on any agent version, regardless of any conditional logic around the call. This is expected behavior.

• Resolution:

  • If RunScript and Unmap are both called directly in the target field's mapping expression, upgrade the private agent to version 12.9 or later.

  • If Unmap is called from inside the script invoked by RunScript, move the Unmap call out of the called script and into the target field's own mapping expression instead, for example:

    RunScript("<TAG>script:MyScript</TAG>"); If(<condition>, Unmap(), <value>);
    

Project management

Storing Design Studio projects on a network file share is not recommended

• Symptom: A Design Studio project stored on a network file share (rather than locally or in Harmony cloud storage) exhibits data loss, where UI changes do not persist after reopening the project, or performance is noticeably slower than expected.
• Possible cause: Jitterbit does not recommend storing Design Studio project workspaces on a network file share. Network file share storage lacks the file locking mechanisms Design Studio requires, leading to inconsistent saves and potential data loss.
• Resolution: Move the project workspace to local storage or use Harmony cloud storage instead of a network file share.

Project download fails with Invalid XML character error

• Symptom: Downloading a project to Design Studio fails with an error indicating that an invalid XML character was found in the element content, for example:

  An invalid XML character (Unicode: 0x15) was found in the element content of the document
  

  or:

  org.xml.sax.SAXParseException; lineNumber: 17499; columnNumber: 21; An invalid XML character (Unicode: 0x5) was found in the element content of the document.
  

• Possible cause: The project metadata contains a control character (such as 0x05 or 0x15) that is not valid in XML. This can result from a corrupted endpoint URL or from unusual characters pasted into scripts, notes, or other text fields.

• Resolution:
  1. Open the project in Design Studio (or use a recent local backup) to inspect the metadata.
  2. Review endpoint URLs, scripts, and notes for invisible or unusual characters and remove or replace them. The line number in the error message can help locate the affected area in the exported XML.
  3. Save and deploy the corrected project, then retry the download from Design Studio.
  4. If the offending content cannot be identified, contact Jitterbit support with the full error message and project ID for possible metadata repair on the backend.

Project components missing after download or import

• Symptom: Opening or importing a project shows operations in the list but no components (transformations, scripts, schemas) appear, or a project export .json file fails to import. The cause is usually a single corrupted component in the project export that breaks parsing of the entire file.
• Possible cause: A component within the project export has malformed JSON, such as an empty body or unusual characters that invalidate the file.
• Resolution:
  1. Export the project from the Harmony portal to produce a .json file.
  2. Open the .json file in a text editor and inspect the components array for entries that appear empty, malformed, or contain unusual characters.
  3. Remove the suspect component's full JSON object from the components array.
  4. Save the file and import it back into Harmony.
  5. If the corruption is not identifiable, send the project export to Jitterbit support for analysis.

Duplicate operations or transformations appear in a downloaded project

• Symptom: Some users downloading the same project see duplicated operations or transformations with identical names and schemas, and those duplicates are flagged as invalid (red-marked) in Design Studio. Other users see a clean version of the same project.
• Possible cause: The project was migrated at the operation level (rather than at the project level), and the migration added duplicate copies of dependencies (such as transformations) into the original project.
• Resolution:
  1. Make a backup of the project before making any changes.
  2. Identify the duplicate operations or transformations. Delete the duplicates while retaining the originals.
  3. Deploy the cleaned project. All users who re-download the project will receive the cleaned version.
  4. To prevent this in the future, avoid using operation-level migration into a project that already contains the source components. Use project-level migration or selectively migrate only the dependencies that are not already present.

Salesforce project import fails with an incorrect version requirement

• Symptom: Importing or opening a project with a Salesforce endpoint fails with an error such as:

  The Jitterpak requires version 12.7.0.0 or higher. The Studio is currently running version [your Design Studio version]. This means that the Jitterpak cannot be opened by this Studio.
  

  This can occur even on a current, supported Design Studio version, because Design Studio has never had a 12.x release.

• Possible cause: The project was exported from Design Studio 11.63 or 11.64. These versions stamp a project containing a Salesforce endpoint with an incorrect required version (12.7.0.0) instead of the correct minimum version. Design Studio 11.64.1 and later export the correct required version.

• Resolution:

  • If the project was exported to a local .jpk file:

    1. Rename the .jpk file to .zip, then extract it.
    2. In environment.properties, change the requires-version value to match your installed Design Studio version, for example: requires-version=11.63.0.0.
    3. In jitterpak.properties, change the required_version value to the corresponding encoded value. For Design Studio 11.63.0.0, use required_version=110630000000000. For any other version, export a new, empty project from your installed Design Studio and copy the required_version and requires-version values from that project's files instead.
    4. Compress the extracted files back into a .zip archive, rename it to .jpk, then import it.

    These steps correct only the .jpk file you edit. Re-exporting the project from Design Studio 11.63 or 11.64 writes the incorrect version requirement again, so upgrade to Design Studio 11.64.1 or later to prevent this.

  • If the error occurs when downloading or opening a project deployed to the Harmony cloud rather than when importing a local .jpk file:

    1. Upgrade to Design Studio 11.64.1 or later.
    2. Contact Jitterbit support to request the backend correction to the project's stored version requirement, which isn't available in the Design Studio UI. Request the correction only after upgrading: opening or re-exporting the project with an older, affected version afterward can write the incorrect version requirement back to the project.

Notifications

SOAP fault fails to deploy when set to trigger an email directly

• Symptom: Configuring a SOAP fault to directly trigger an email notification fails to deploy or does not work as expected.
• Possible cause: Deploying an operation in which a SOAP fault directly triggers an email message can produce an error.
• Resolution:
  1. Configure the SOAP fault to trigger an operation instead.
  2. In that operation, use the SendEmailMessage function in a script to send the notification email.

FTP and file sources

File transfers repeat unexpectedly

• Symptom: An operation re-transfers a source file that was already processed in a previous run.
• Possible cause: Design Studio tracks three criteria to determine whether a file has already been transferred: file name, modification date, and operation ID. If any of these values has changed since the last transfer, Design Studio treats the file as new and transfers it again.
• Resolution: To prevent a specific file from being re-transferred, delete its entry from the transfer history list: select the checkbox next to the entry in the lower pane and click Delete.

FTP: Passive mode and high-port firewall restrictions

• Symptom: An FTP source connects successfully from a workstation but fails when the operation runs on the private agent, or file transfers time out despite the agent being able to reach the FTP server.
• Possible cause: FTP passive mode uses dynamically assigned high-numbered ports for data transfers. Firewalls that restrict outbound connections to well-known ports block these data channel connections, even when the control channel (port 21) is open.
• Resolution:
  • Confirm that Passive Mode is enabled in the FTP source configuration (it is enabled by default).
  • Work with your network administrator to open the high-numbered port range used by your FTP server for passive data connections on the firewall between the private agent host and the FTP server.

FTP: Success and error folder paths are on the agent, not the FTP server

• Symptom: Files are not appearing in the configured success or error folder after an FTP operation runs, or the paths appear to resolve to unexpected locations.
• Possible causes:
  • The success folder and error folder path fields in an FTP source refer to directories on the private agent machine, not on the remote FTP server. Relative paths are interpreted relative to the agent host's file system.
  • Filename keyword variables are not resolved in these fields.
• Resolution:
  • Enter absolute paths on the private agent host for the success and error folder fields (for example, C:\Jitterbit\processed\ on Windows or /var/jitterbit/processed/ on Linux).
  • Do not use filename keywords or special characters such as * in these path fields.
  • Confirm the agent service account has write permissions on the configured directories.

FTP: Directory listing cannot be parsed

• Symptom: An FTP source fails to list files, or known files are missing from the source even though they exist on the FTP server.
• Possible cause: Some FTP servers return directory listings in a non-standard format that Design Studio cannot parse using its default parser.
• Resolution:
  • In the FTP source configuration, enable List only filenames. This causes the source to use the NLST command, which returns only filenames rather than a full directory listing and is more widely supported across FTP servers.
  • Alternatively, set the Jitterbit variable jitterbit.source.ftp.enable_regex_parser to true upstream of the FTP read step to enable a more flexible listing parser.

FTP target: Use FTP Rename is not functional with SFTP archive operations

• Symptom: Files written to an SFTP server using an FTP target with Use FTP Rename enabled fail or are not written correctly when the operation type is archive.
• Possible cause: The Use FTP Rename option is not functional when writing to an SFTP server in an archive operation.
• Resolution: In the FTP target configuration, clear the Use FTP Rename checkbox when the target server is an SFTP server and the operation writes an archive file.

FTP target: Auto Create Directories is unreliable

• Symptom: An FTP target operation fails because a target directory does not exist, even though Auto Create Directories is enabled.
• Possible cause: It is a known issue that the Auto Create Directories option works inconsistently. Depending on the particular FTP server, the directory may not be created.
• Resolution:
  • Manually create the required directories on the FTP server before running the operation.
  • If you use Auto Create Directories, confirm the directory has been created before relying on it in production.

File Share source: Individual files larger than 2 GB cannot be retrieved

• Symptom: Retrieving a large file from a File Share source fails, even though the file exists and the source connection is configured correctly.
• Possible cause: File Share sources have a known limitation where individual files larger than 2 GB may not be retrievable.
• Resolution: Split files larger than 2 GB into smaller segments before placing them in the file share for retrieval.

HTTP source

Connection test fails even when the endpoint is reachable

• Symptom: Testing an HTTP source connection fails with a connection or authorization error, but the endpoint is confirmed reachable and returns data when accessed directly in a browser or API client.
• Possible cause: The Test Connection button in the HTTP source configuration sends an HTTP HEAD request. Some servers do not support the HEAD method and return a 405 or similar error, even though GET and POST requests succeed.
• Resolution:
  1. If the endpoint is confirmed reachable in a browser or via a direct GET/POST request, the failed connection test can be disregarded. Proceed with deploying and running the operation to verify actual connectivity.
  2. If the operation also fails at runtime, investigate further using the operation logs.

NetSuite connector

Data center URL error: Use account-specific WSDL URL

• Symptom: A NetSuite endpoint that previously connected successfully now fails with:

  Connector Error: Error getting the data center URL.
  ...
  In this account, you must use account-specific domains with this SOAP web services endpoint.
  

  or:

  You are not requesting the correct data center for your company.
  

• Possible cause: NetSuite no longer accepts generic WSDL URLs (for example, https://webservices.netsuite.com/...) or data center-specific WSDL URLs (for example, https://webservices.na3.netsuite.com/...). The endpoint must use an account-specific WSDL URL.

• Resolution:
  1. In NetSuite, go to Setup > Company > Company Information and open the Company URLs tab to find the account-specific domain.
  2. Construct the account-specific WSDL URL in the format https://<account-id>.suitetalk.api.netsuite.com/wsdl/v2025_1_0/netsuite.wsdl.
  3. Update the WSDL Download URL field in the NetSuite endpoint configuration with the account-specific URL.
  4. For full instructions, see NetSuite account-specific WSDL URL.

TFA users must not use SSO authentication type

• Symptom: A NetSuite endpoint configured with single sign-on (SSO) authentication fails or behaves unexpectedly for a user with two-factor authentication (TFA or 2FA) enabled on their NetSuite account.
• Possible cause: NetSuite users with TFA enabled should not use the SSO authentication type when configuring a NetSuite endpoint. This combination can cause the endpoint to fail. The SSO authentication type is also being phased out by NetSuite.
• Resolution:
  1. Enable token-based authentication (TBA) on the NetSuite account.
  2. Reconfigure the NetSuite endpoint to use TBA instead of SSO.

TBA: INSUFFICIENT_PERMISSION error at runtime despite successful connection test

• Symptom: A NetSuite endpoint configured with token-based authentication (TBA) tests the connection successfully, but operations fail at runtime with:

  INSUFFICIENT_PERMISSION
  

• Possible cause: The role used to generate the TBA access tokens does not have sufficient permissions for the operations being run. The connection test succeeds even with an under-permissioned role, but runtime permission checks fail.

• Resolution:
  1. In NetSuite, switch to a Full Access or Administrator role when generating the access tokens, or add the required permissions to the current role.
  2. Regenerate the access tokens using the updated role and reconfigure the NetSuite endpoint.

Saved search dropdown is empty when object has more than 1,000 saved searches

• Symptom: The saved search dropdown in the NetSuite activity configuration does not populate with any options, even though saved searches exist for the object in NetSuite.
• Possible cause: NetSuite imposes a 1,000-record limit on API requests. If an object has more than 1,000 saved searches, the API request to retrieve them exceeds this limit and returns no results, leaving the dropdown empty.
• Resolution: In NetSuite, delete or archive saved searches that are no longer in use to reduce the total count below 1,000 for the affected object. The dropdown will populate once the count is reduced. For more details, see NetSuite saved search limitations.

NULL or blank values cannot be passed to NetSuite custom fields

• Symptom: Mapping a NULL or blank (empty string) value to a NetSuite custom field does not clear the field in NetSuite.
• Possible cause: The NetSuite API does not accept NULL or blank values for custom fields through the standard field mapping approach.
• Resolution: To pass NULL or blank values to a custom field, map the source field to both the externalId and name child fields of the custom field target node in the transformation. For more details, see Passing null values to custom fields.

Custom segments not displayed in activity configuration

• Symptom: Custom segments do not appear in the NetSuite activity configuration screen when they are expected to be available for mapping.
• Possible cause: The NetSuite user account configured in the endpoint does not have sufficient permissions to access the custom segment or the object it is associated with.
• Resolution:
  1. In NetSuite, verify that the user account configured in the NetSuite endpoint has the appropriate permissions to interact with the custom segment and its associated object.
  2. If the permissions are insufficient, update the user role in NetSuite to include the required custom segment access.

SAP connector

IDocs not found when a scheduled operation runs on a different agent

• Symptom: In a multi-agent group using store-and-forward IDoc processing, the scheduled operation that scans for stored IDoc files finds no files to process on some runs, and IDoc processing is delayed or occurs out of order.
• Possible cause: In store-and-forward processing, the SAP Event Listener stores each received IDoc on the local file system of the agent that received it. A separate operation on a fast schedule then scans for and processes those files, but Harmony can dispatch that scheduled operation to any agent in the group. Each agent processes only the files stored on itself, so files stored on one agent are not processed until the schedule next selects that agent.
• Resolution: Each agent processes its own stored files the next time the scheduled operation runs on it, so the files are eventually processed. If IDocs must be processed in a guaranteed order, or without waiting for the storing agent's next scheduled run, write the IDoc files to a shared resource that all agents can access, such as an FTP site, a shared file system, or a database. Note that an external data store adds a point of failure; agent clusters are otherwise used for failover and load balancing.

Bulk IDoc sends can exceed target endpoint connection limits

• Symptom: After a large SAP bulk operation sends thousands of IDocs, operations against a downstream target system (such as Salesforce) fail intermittently with connection or login limit errors.
• Possible cause: IDocs are sent asynchronously. When thousands of IDocs are generated by a bulk update, all of them attempt to trigger their downstream operations simultaneously. Systems such as Salesforce enforce concurrent API connection limits, and a sudden flood of IDoc-triggered operations can exceed those limits.
• Resolution:
  • Use a store-and-forward pattern: configure the IDoc listener to write incoming IDocs to temporary files, then use a scheduled operation to process them in controlled batches at a predictable rate.
  • Review the target endpoint's concurrent connection and API call limits and configure the Design Studio operation to stay within those limits by throttling the number of simultaneous operations.

SAP IDoc payload lost when target endpoint is unreachable

• Symptom: An IDoc is received by the SAP Event Listener but the data does not arrive at the target endpoint and cannot be recovered.
• Possible cause: In straight-through processing, if the target endpoint is unreachable when the IDoc is processed, the payload is not delivered and is permanently lost. There is no automatic retry mechanism in straight-through processing.
• Resolution: Use store-and-forward processing instead: configure the first operation to write the incoming IDoc to a temporary file, then use a scheduled operation to process the file. If the target is unreachable, the file is retained and reprocessed on the next scheduled run. For guidance on implementing store-and-forward processing, see Best practices for SAP.

SAP IDoc store-and-forward: Temporary files deleted after 24 hours

• Symptom: In a store-and-forward IDoc workflow, temporary files that have not been processed are missing from the storage directory before the processing operation has run.
• Possible cause: By default, temporary IDoc files in store-and-forward processing are automatically deleted after 24 hours. If the scheduled processing operation does not run within that window (for example, due to agent downtime), the files are removed before they can be processed.
• Resolution:
  • Ensure the scheduled processing operation runs at least once every 24 hours to process files before they expire.
  • Alternatively, increase the retention period if a longer window is required. For details, see Best practices for SAP.

BAPI operation succeeds but transaction is not committed to SAP

• Symptom: Running a BAPI appears to execute without error, but the expected transaction does not appear in SAP.
• Possible cause: The SAP Connector issues a BAPI transaction commit only when the BAPI returns a response type of S (Success). If the BAPI returns a response type of I (Information), E (Error), or W (Warning), no commit is issued and the transaction is not saved to SAP.
• Resolution:
  1. Check the RETURN node's TYPE field in the BAPI response to confirm the response type that is being returned.
  2. If you are using a customized BAPI, update it to return a response type of S when the transaction should be committed. For more details, see Troubleshooting BAPI commits.

SAP Event Listener does not pick up IDocs on Windows

• Symptom: The SAP Event Listener service is running, the SAP system reports outbound IDocs as successfully sent, but no operations are triggered. Agent logs show connection errors for the RFC program ID, such as:

  serverException occured on [Program ID] connection null
  

• Possible cause: The Windows services file on the agent host does not contain an entry for the SAP gateway service. Without this entry, the RFC program ID listener cannot resolve the SAP gateway hostname and port, preventing iDocs from being delivered to Design Studio.

• Resolution:

  1. On the Windows host running the private agent, open %WINDIR%\System32\drivers\etc\services as an administrator.

  2. Add the following lines:

     sapgw00 3300/tcp
     sapgw00 3300/udp
     

  3. Save the file, restart the SAP Event Listener service and the agent, and retest by sending an IDoc from SAP.

The service name sapgw00 and port 3300 correspond to the default SAP gateway service for system number 00. If your SAP system uses a different system number, adjust the entries accordingly (for example, sapgw01 3301/tcp and sapgw01 3301/udp for system number 01).