EDI troubleshooting

This guide covers common errors and issues encountered when using Jitterbit EDI. 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 a Studio operation that integrates with Jitterbit EDI (for example, one that uses the EDI for Cloud v2 connector), see operation troubleshooting, or private agent troubleshooting if the operation runs on a private agent.

Diagnostic steps

Check the transaction status

Open the Transactions page and filter for failed or rejected transactions. The status and any associated error message shown for the transaction are the primary indicators of what went wrong.

Check the Messaging page

The Messaging page shows EDI system log messages. To find messages related to a failed transmission or document, filter by Error status, trading partner, severity level (High, Medium, Low, or Info), and message category. For transmission problems, filter by the Communication category (AS2, FTP, and VAN channels); for document processing problems, filter by the Transaction category (Processor and Validation).

Check the Archive page

The Archive page contains the raw inbound and outbound EDI documents for archived transactions. Reviewing an archived document can confirm whether a failure is in the document content itself or in the processing logic.

Check the operation and agent logs

If your integration uses the EDI for Cloud v2 connector in a Studio operation, first review the operation logs for errors from the operation run. If the operation runs on a private agent and you need lower-level detail such as connectivity errors, also review the agent logs.

EDI communication failures

AS2 connection or certificate failure

• Symptom: Outbound AS2 transmissions fail or trading partner acknowledgments are not received.
• Possible causes:
  • The AS2 certificate has expired or is no longer trusted by the trading partner.
  • The certificate algorithm does not match what the trading partner requires (for example, SHA-1 vs. SHA-256).
  • The AS2 endpoint URL, partner ID, or other connection parameters are incorrect.
  • A firewall or network restriction is blocking outbound AS2 traffic on port 443 or the configured AS2 port.
• Resolution:
  • Review the AS2 communication settings for the affected trading partner and confirm the endpoint URL, partner IDs, and certificate settings are correct.
  • Check the certificate expiry date and renew it if it has expired. Re-exchange the updated certificate with the trading partner.
  • Confirm the certificate algorithm matches the trading partner's requirements. Update the algorithm in the AS2 settings if needed.
  • Verify that outbound traffic to the trading partner's AS2 endpoint is permitted by your network firewall.

AS2: Trading partner's firewall must allowlist Jitterbit IP addresses

• Symptom: A trading partner reports that they cannot receive your AS2 transmissions, or their AS2 acknowledgments never arrive, even though your outbound AS2 settings appear correct.
• Possible cause: The trading partner's firewall requires an explicit allowlist for inbound traffic and has not added the Jitterbit EDI IP addresses.

• Resolution:

  • Provide the following Jitterbit EDI IP addresses to your trading partner and request they allowlist them for inbound and outbound AS2 traffic:

    • North America: 40.71.22.62
    • EMEA and APAC: 20.166.31.85

  • For your inbound AS2 receiving URL and the corresponding IP address to give to trading partners, see the AS2 communication settings page for your region.

FTP or SFTP connection failure

• Symptom: FTP or SFTP transmissions to or from a trading partner fail, or file transfers hang and time out.
• Possible causes:
  • The server address, port, credentials, or authentication method (password vs. SSH key) are incorrect or outdated.
  • A firewall or network restriction is blocking the required port between Jitterbit EDI and the FTP/SFTP server.
  • The target directory does not exist or the service account lacks read/write permissions on it.
  • The host key has changed on the SFTP server, causing a mismatch.
• Resolution:
  • Review the FTP communication settings for the affected trading partner and verify all connection parameters.
  • Confirm that connectivity to the FTP/SFTP server address and port is permitted through the relevant firewalls.
  • Verify that the service account has the required permissions on the target directory.
  • If using SSH key authentication, confirm the key is current and accepted by the server. If the host key has changed, update the known hosts entry.

Duplicate transaction check does not apply to EDIXml or XCBL format

• Symptom: Duplicate inbound documents are being processed multiple times even though the Duplicate Transaction Check setting is enabled on the trading partner's AS2 connection.
• Possible cause: The Duplicate Transaction Check applies only to EDI-format documents. It does not filter duplicates for EDIXml or XCBL interchange formats.
• Resolution: If duplicate filtering is required for EDIXml or XCBL workflows, implement deduplication logic in the Studio operation that processes the inbound documents (for example, checking a transaction ID against a database or Cloud Datastore record before processing).

VAN connectivity issues

• Symptom: EDI documents are not being delivered or received through a Value Added Network (VAN).
• Possible cause: A VAN connection is a managed connection that Jitterbit sets up; you cannot create or configure it yourself. Delivery failures typically involve the VAN interconnect, mailbox routing, or partner setup on the provider's side rather than a self-service setting in Jitterbit EDI.
• Resolution:
  • Confirm the correct VAN connection is assigned to the affected trading partner.
  • Because the VAN connection cannot be configured from Jitterbit EDI directly, contact Jitterbit support or your Customer Success Manager to verify the VAN interconnect and document routing.
  • Coordinate with the VAN provider to confirm the trading partner's mailbox identifiers and routing are correct on the VAN side.

EDI for Cloud v2 activity fails on a private agent behind a firewall or proxy

• Symptom: On a private agent, an EDI for Cloud v2 activity such as Get Document fails to retrieve data (for example, with an "Unable to fetch data" error), even though the connection test succeeds and the same project works on a cloud agent group.
• Possible cause: The private agent is behind a firewall or proxy that blocks outbound access to the Jitterbit eiCloud EDI service at eicloudservice.com. The EDI for Cloud v2 connector calls this service (for example, at *.transactionapi.eicloudservice.com) to retrieve data, so blocking it causes the activity to fail. Cloud agents are not affected.
• Resolution:
  1. Allowlist eicloudservice.com and its subdomains for outbound access on the private agent's network, firewall, and proxy. For the other Jitterbit domains and IP addresses a private agent needs for outbound access, see Allowlist information.
  2. If a proxy is in use, confirm it is configured correctly on the private agent and is not interfering with the connection.

EDI access token deactivated causes INVALID_TOKEN error

• Symptom: Operations using the EDI for Cloud v2 connector fail with:

  Error opening connection. Exception is: Error code: INVALID_TOKEN
  

• Possible cause: The access token used by the EDI for Cloud v2 connection has been set to Inactive on the Management Console Access Tokens page.

• Resolution: On the Access Tokens page, locate the token and set its Status to Active.

Document processing errors

Document rejected: Invalid or missing data

• Symptom: An outbound EDI document is rejected by the trading partner or fails validation, or an inbound document produces a negative acknowledgment.
• Possible causes:
  • A required segment or data element is missing from the document.
  • A field value exceeds the allowed length, uses an incorrect data type, or contains invalid characters.
  • The interchange usage indicator (ISA15) is set to T (test) instead of P (production), so the trading partner rejects the document.
  • The document does not conform to the trading partner's implementation guide.
• Resolution: Review the rejected transaction on the Transactions page for the specific segment or element cited in the error, then:
  • For a document you sent, compare it against the trading partner's implementation guide to identify missing or non-compliant fields, then update the EDI mapping and settings for the affected document type to produce compliant output.
  • For an inbound document sent by the trading partner, share the validation error with them so they can correct their outgoing format.

EDI mapping or schema error

• Symptom: EDI documents are generated with incorrect content, missing fields, or an unexpected structure, or inbound documents fail to process correctly.
• Possible causes:
  • The EDI map or schema is outdated and does not reflect the current implementation guide or trading partner requirements.
  • Source data fields are mapped incorrectly, producing wrong values in the output document.
  • Data type mismatches, special characters, or encoding issues in the source data cause transformation failures.
• Resolution:
  1. Review the EDI settings for the affected trading partner under EDI settings and verify that the map accurately reflects the current implementation guide.
  2. Validate that source data fields are mapped to the correct EDI segments and elements.
  3. Check source data for special characters, encoding issues, or unexpected values that may be causing transformation failures and add data cleaning steps if necessary.
  4. Test with a representative sample document and use the archive to compare the generated output against the expected structure.

Transformation error: Unrecognized field in EDI for Cloud v2 activity

• Symptom: A transformation using an EDI for Cloud v2 activity (such as List Transactions) fails with a JSON parsing error referencing an unrecognized field name, for example:

  Unrecognized field "user_defined_field_1"
  

• Possible cause: The version of the EDI for Cloud v2 connector installed on the agent is out of date. The backend EDI service returns a field (such as user_defined_field_1) that the older connector version does not recognize, so the connector cannot parse the response.

• Resolution: Update the EDI for Cloud v2 connector on the agent to the latest version, following Confirm connector availability and keep it current in the connector troubleshooting guide. Clicking Test Connection on the EDI for Cloud v2 connection downloads the latest connector version to the agent; if the Disable Auto Connector Update organization policy is enabled, instead update the connector for the agent group from the Management Console Agents page.

Repeating EDI segment or loop maps only the last iteration

• Symptom: In a Studio transformation, a repeating segment or loop in an EDI document handled through the EDI for Cloud v2 connector maps only its last occurrence (earlier iterations are dropped), because the node's cardinality in the connector's activity schema is single-occurrence (for example, (0,1)) instead of repeating ((1,many)). This affects both X12 (for example, an N9 segment nested within an LX loop in a 945) and EDIFACT (for example, a repeating CNI group in an IFCSUM).
• Possible cause: The auto-generated schema provided by the EDI for Cloud v2 connector does not reflect the correct cardinality for the affected segment or loop. The raw document in the EDI Transactions store contains all iterations, and a schema built manually from that raw XML maps them correctly, which confirms the connector's response schema (not the data) as the cause.
• Resolution:
  1. Open the EDI for Cloud v2 connection in Studio and refresh the metadata to check whether a schema correction has been released.
  2. If the cardinality is still incorrect after refreshing, export the schema, manually update the maxOccurs attribute on the affected segment in an external XML editor, and re-import it as a custom XSD.

Adding nested hierarchical loop (HL) levels to an EDI transformation

• Symptom: When building a Studio transformation for an EDI transaction set that uses hierarchical loops (for example, X12 870 4010VICS, which is structured much like the 856), the schema from the EDI for Cloud v2 connector's Send Document activity shows a single HL level, but the document you need to produce requires nested HL levels (for example, an HL-O order level with a child HL-I item level).
• Possible cause: Hierarchical documents can nest HL levels to varying depths, so the connector's schema exposes a single HL level that you replicate in the transformation to build the additional levels your document requires.
• Resolution:
  1. In the target schema tree of the transformation, right-click the existing HL node and select Duplicate node to add the nested HL level (for example, a child HL-I level under HL-O).
  2. Map the duplicated node to your source data. Add a condition on the duplicated node if it should be created in the output only under specific circumstances.

Trading partner configuration

Incorrect trading partner identifiers

• Symptom: Documents are routed incorrectly, rejected at the envelope level, or not recognized by the trading partner.
• Possible causes:
  • The sender or receiver EDI ID, qualifier code, or other envelope-level identifiers do not match what the trading partner expects.
  • The trading partner's configuration was recently updated but the change was not applied in Jitterbit EDI.
• Resolution:
  1. Review the trading partner's configuration and confirm the EDI ID and qualifier codes match the values specified in the trading partner's setup documentation.
  2. Compare the envelope identifiers in a rejected document (visible in the archive) against the expected values.
  3. Update the trading partner settings if any identifiers are incorrect, then reprocess or resend the affected documents.

EDI ID override values not applied to outbound transactions

• Symptom: Outbound transactions use the default sender or receiver EDI IDs from the trading partner configuration rather than the preferred override IDs configured in the EDI ID settings.
• Possible cause: EDI ID overrides are not applied automatically. The preferred IDs must be explicitly mapped in the request transformation of the Studio operation that sends the outbound document using the EDI for Cloud v2 connector.
• Resolution: In that request transformation, map values to these fields to apply the preferred IDs (refer to the EDI ID settings page for the exact values to use):
  • ISA05_ID_Qualifier: sender ID qualifier
  • ISA06_Sender_ID: sender EDI ID
  • ISA07_ID_Qualifier: receiver ID qualifier
  • ISA08_Receiver_ID: receiver EDI ID

Acknowledgments not configured or not received

• Symptom: Expected 997 (X12) or CONTRL (EDIFACT) functional acknowledgments are not being sent or received, or acknowledgment processing is not functioning as expected.
• Possible causes:
  • Acknowledgment generation or processing is disabled in the trading partner's EDI settings.
  • The acknowledgment document type is not included in the trading partner's workflow configuration.
  • The trading partner is not sending acknowledgments, or their acknowledgments are being routed incorrectly.
• Resolution:
  • In the trading partner's EDI settings, confirm that acknowledgment generation and processing are enabled for the relevant document types.
  • Review the manage workflows configuration to confirm the acknowledgment document type is included in the workflow.
  • Check the archive to determine whether acknowledgments from the trading partner are being received but not processed, or are not arriving at all.
  • If acknowledgments are not arriving, coordinate with the trading partner to confirm they are sending them to the correct endpoint.

Cannot delete an assigned communication connection

• Symptom: Attempting to delete an AS2 or FTP connection in the Communication settings fails or the delete option is unavailable.
• Possible cause: Assigned connections cannot be deleted. A connection that is currently assigned to a trading partner must be unassigned before it can be removed.
• Resolution:
  1. In Communication settings, select the trading partner that uses the connection and assign a different connection to that partner.
  2. Once no partners are using the connection, the delete option becomes available.

FTP "Next Run Time" does not update without a page refresh

• Symptom: The Next Run Time displayed in a trading partner's FTP communication settings remains stale after the scheduled FTP job has run, even though the schedule is working correctly.
• Possible cause: The UI refreshes scheduled-job status only when the page is loaded or when a manual action triggers a data reload. It does not poll the engine in real time.
• Resolution:
  • Refresh the browser page to update the Next Run Time display.
  • Alternatively, navigate away from the FTP settings and back to force a reload.

EDI ID addition fails: ID already in use in another environment

• Symptom: Adding an EDI ID to a trading partner fails even though the ID is not in use in the current environment.
• Possible cause: Each EDI ID must be unique across all Harmony environments where Jitterbit EDI is enabled. If the same ID is already assigned to a trading partner in a different environment, the addition fails.
• Resolution:
  • Check all other Harmony environments where EDI is enabled to confirm whether the ID is already assigned there.
  • Work with your trading partner to establish a unique EDI ID for each environment where you exchange documents.
  • For non-production environments, use a distinct ID that differs from your production EDI ID.

Workflow configuration

Outbound documents pass local validation but fail trading partner testing

• Symptom: Outbound EDI documents pass the local validation check in Jitterbit EDI but are rejected during trading partner testing or certification, often with errors about missing or non-compliant elements.
• Possible causes:
  • Outbound validation is disabled in the workflow configuration. Jitterbit EDI allows documents to be generated without validation, but without it, documents may lack elements required by the trading partner's implementation guide.
  • The EDI settings cover the essential elements of the standard, but the trading partner's implementation guide may require additional mandatory elements not enforced by default settings.
• Resolution:
  • In the manage workflows configuration, enable validation for the outbound workflow.
  • Review the trading partner's implementation guide for any mandatory elements beyond the standard EDI settings and add them to the mapping.
  • Unless you have a thorough understanding of the specific EDI transaction and trading partner requirements, always enable validation before testing with a trading partner.

Archive and transactions

Transaction archived earlier or later than expected

• Symptom: A transaction is archived before the expected retention period ends, or it remains available longer than expected.
• Possible cause: Transactions are archived based on the later of two dates: the transaction date and the document date. If the document date is more recent than the transaction date, archival is calculated from the document date, which can extend the retention period.
• Resolution:
  • When investigating unexpected archival timing, check both the transaction date and the document date for the affected transaction.
  • Review the retention period settings to confirm the configured number of days (30, 60, or 90).

Permissions and access

Cannot access EDI features

• Symptom: A user cannot view or interact with EDI pages, or certain EDI actions are unavailable.
• Possible causes:
  • EDI access requires both an EDI-specific role permission (Admin, EDI User, or EDI Viewer) and a Write-level environment access role. Missing either one prevents access.
  • The EDI User and EDI Viewer roles differ in what they allow. EDI Viewer can reprocess transactions, resend acknowledgments, and read pages, but cannot create or update configurations or upload files. Creating or updating configurations and uploading files for processing require the EDI User role. Administrative actions, such as archiving transactions, enabling PII, and changing purge settings, require the Admin role.
• Resolution:
  • In the Management Console, verify the user has a role that includes the Admin, EDI User, or EDI Viewer permission.
  • Confirm the user's environment access level includes Write access for the environment where EDI is configured.
  • If the user needs to perform write operations (such as creating trading partners or uploading documents), assign the EDI User role rather than EDI Viewer. See EDI permissions for the full permission matrix.

Cannot enable PII settings

• Symptom: The option to enable PII (personally identifiable information) settings for a trading partner is unavailable or greyed out.
• Possible cause: Enabling PII settings requires the Admin permission. Neither the EDI User nor the EDI Viewer role can enable PII settings.
• Resolution:
  • Confirm the user's role includes the Admin permission, not just EDI User or EDI Viewer.
  • If the user needs to manage PII settings regularly, update their role assignment accordingly.