Troubleshooting Guide

This guide will cover some of the common pitfalls in setting up AS2 connectivity with your partners, and ways to rectify those. Feel free to contact support@as2gateway.com for more details.

For AS2 message/transaction related issues (such as outgoing message failures), you may also obtain direct help from the message dashboard by clicking the “Explain why this message failed” (info “i” icon) button displayed adjacent to the message subject field:
If you do not receive a satisfactory explanation, or if you would like to suggest an improvement to the automated explanation, feel free to contact the support team anytime.

1 Registration

Q: I cannot create an account on AS2 Gateway.

The accompanied error usually gives a hint on what is wrong, and what you can do next.

Register button is disabled: Make sure you have filled in all the mandatory fields, including Domain, Organization, Full Name and Email, and have also read and agreed to the Terms and Conditions by checking the corresponding check-box.
An alert with no content appears when clicking Register: You (or someone else using your IP address) has tried to register too many times with bad/conflicting information; please retry after 1 minute, and contact support if the problem persists.
Provided email already exists in the system: You (or - although unlikely - someone else) have already registered on AS2 Gateway using the provided Email address. If this was you, try to log in instead, or require a password reset via the log-in page itself. If you are certain that you have not already registered, contact support immediately.
A tenant already exists with the provided domain: The requested domain name is already being used in AS2 Gateway; another user from your organization/domain may already have registered an account. Check with your organization, and if it is confirmed that no one else has registered, contact support immediately.
Provided email doesn’t belong to the tenant: The domain name part in your email address, does not match the domain name in your organization details. For example, your domain name is some.domain.com but your email address is yourname@another.domain.com. Change your domain name (e.g. to another.domain.com) or email address (e.g. to yourname@some.domain.com), so that both have the same domain.
Any other error would indicate a temporary glitch; please try again after a minute, and contact support if the problem persists.

Q: I have created an account on AS2 Gateway, but I am getting an error when trying to log in.

Usually the displayed error, contains details of what went wrong - and the next action to take.

User email has not been verified yet: You need to activate your account by clicking the verification link sent to the registered email, before you can log in.
Authentication Failed: Bad credentials: You entered a wrong email-password combination; if your password is correct, you are probably trying to log in using a different email address (e.g. you created the account using your corporate email but are now trying to log in using your personal email; or vice versa).
Blocked due to too many login attempts: You have made too many login attempts with invalid email-password combinations, and the system has temporarily locked you out as a security measure. Please try to log in again, making sure that you are using the correct credentials, after one hour; or contact support for a quicker resolution.
User account is locked: Your account has been disabled, either due to expiration of the subscription or free trial period, or because you have violated AS2 Gateway Terms of Service (one common reason could be that you or your organization has registered multiple accounts over time). The support team would already have sent you a reminder/notification regarding the disablement; if not, you can raise a query for more information.
Any other error would indicate a temporary glitch; please try again, and contact support if the problem persists.

Q: I have registered, confirmed my account and logged in, but have no idea what to do next.

Visit our user guide to create the necessary trading entities and start exchanging AS2 messages.

2 Sending Messages

Q: When I go into the ‘Compose Message’ page, there is no way/option to submit a file.

You need to create a trading station (sender) and trading partner (receiver) before you can send/receive files; please follow our user guide to get the necessary things set-up.

Q: Outgoing messages have failed with connectivity errors.

The Failure Reason column of the failed messages may contain an error similar to:

NoRouteToHostException: No route to host. Error occurred while attempting to connect to the partner URL.
ConnectException: Error occurred while attempting to connect to remote address and port in the partner URL.

Generally this error suggests an issue with making a POST request to the given partner URL. In order to troubleshoot this, we need to check if the partner’s domain and port is publicly accessible.

Say the partner URL is http://myas2partner.com:8082/as2. To make sure the partner domain and port is accessible to the public, the telnet command can be used. telnet <host> <port>

E.g.:

> telnet myas2partner.com 8082
telnet: could not resolve myas2partner.com/8082: Name or service not known

If the output of the command is something similar to the one shown above:

The partner URL you have configured might be incorrect; perhaps there might be a typo. Therefore, first make sure the hostname and port in the partner URL (myas2partner.com and 8082 respectively, in the above example) is correct. If the URL is correct, check with your partner regarding whether public DNS routing has been set up for myas2partner.com

If the output is similar to:

telnet: Unable to connect to remote host: Connection timed out or telnet: Unable to connect to remote host: Connection refused

There might be a firewall blocking the requests coming from the AS2 Gateway. You’ll have to contact your partner to check if it is actually the cause; if so, ask the partner to whitelist the AS2 Gateway IP 52.204.119.191, and try again once the IP is whitelisted. If you continue to get the latter error (Connection refused) when AS2 Gateway is whitelisted, double-check whether the port (8082 in the above example) in the partner URL is correct. If you are running the telnet command in a Windows system, you may not receive detailed errors like the above (the output may resemble Connecting To myas2partner.com… Could not open connection to the host, on port 8082: Connect failed). In that case, follow each of the above steps to determine and fix the issue. Alternatively, if you have access to a MacOS/Linux system, try running telnet there to see more detailed error messages.

There might be cases where you are trying with your own IP address as the partner URL. In such cases make sure that the IP address you assign is a publicly accessible IP address. Note that IP addresses in the private address spaces will fail while attempting to connect.

Q: My outgoing messages end up in the Failed folder, with HTTP error NNN:..

Your partner’s system is rejecting the messages sent by AS2 Gateway, with HTTP error responses. The error code gives a hint of what may be wrong:

301/302/307: partner is trying to redirect the message. A common scenario is that the partner is expecting a message over HTTPS but you have configured a HTTP URL (http://) on AS2 Gateway side.
400: client error. For some reason, partner’s system sees AS2 Gateway’s message as invalid. This can be due to a variety of causes; see below.
401: unauthorized/login required. Some partners require, in addition to standard AS2 metadata, authorization parameters to allow the request to pass through. These can usually be provided via custom HTTP headers; contact your partner for more details.
403: forbidden. Usually happens when the partner URL you configured on AS2 Gateway side is incorrect, but can also indicate that your trading configuration has not yet been set up on the partner’s end; see below.
404: not found. Most probably the partner URL you entered is incorrect, or has an additional character (e.g. whitespace) appended/prepended.
405: method not allowed. Again, most probably an incorrect partner URL.
413: payload too large. You are trying to send content that exceeds the maximum size accepted by your partner. (Please note that the composed AS2 message is usually larger than the original file you uploaded; especially when the file is binary rather than text.
500: internal server error. Something is wrong with partner’s server/endpoint.
502: bad gateway. Partner’s AS2 server is down, and a front-line (proxy) server is returning an error on its behalf.
503: service unavailable. Partner’s AS2 server is down.

In any case, the Failure Reason on the message would contain additional details, including (a portion of) the response body returned by the partner’s server (possibly containing an error message), and the response headers (sometimes including hints of the issue); e.g.

for 401, a WWW-Authenticate header may indicate the required authentication scheme.
an HTTP header returned by an integration platform, may contain clues of the actual processing error that happened on the partner’s side.

If none of these details is helpful in determining the cause of the error, contact your partner with the time and AS2 message identifier (Message-ID) of the failed message for more details.

Q: My outgoing messages appear in the Sent folder, but the MDN field is highlighted in red.

This means that your partner’s AS2 system has received the message, but has failed to process/validate it; so it has returned an error MDN (negative receipt) indicating the issue.

You can check the error message returned in the MDN by clicking the message list entry and checking the MDN Failure Reason field. The complete human-friendly message returned within the MDN, will also be displayed if you hover over the colored MDN label.

Usually the error message contains enough details to determine the cause of the error and make corrections; which may be on your end or your partner’s. Common cases include:

Decryption failed: you have configured an incorrect encryption certificate for your partner; or your partner has changed their certificate without informing you.
Authentication failed/Signature verification failed: partner’s system has not correctly added/configured your trading station’s certificate; or you have changed your trading station’s certificate without informing your partner.
Insufficient message security: partner expects messages to be signed and/or encrypted, but you are sending without either/both; or the sign/encrypt algorithms configured on your side do not match or meet the expectations of your partner.
Unexpected processing error: unknown error (possibly temporary) on partner’s end; you would need to discuss with the partner for further action/reconciliation.

Q: Getting “Error while parsing certificate” when attempting to import a certificate or creating an AS2 station.

This error suggests an error with the certificate which you are trying to upload. Most common scenarios where this could happen are as follows.

Attempting to import a PFX in place of a JKS

AS2 Gateway as of now only supports JKS (Java KeyStore) type keystores. Thus when a user tries to import a PFX (Windows-based file format for a password protected key and certificate bundle) formatted keystore in place of a keystore of type JKS a parsing error could occur. In this case, you would need to convert it to JKS format before uploading. You can find more details in this answer.

Attempting to upload an invalid certificate

Another case where parsing error would occur is when the certificate is not a valid one. One such case is when the certificate does not include the “Validity Period” which is a required field.

Attempting to upload a CSR instead of a certificate

This error is also quite common among the users who are getting started with AS2. A CSR file is a certificate signing request and is not equivalent to a certificate.

3 Receiving Messages

Q: Failing to verify the signature of the incoming messages and the AS2 Gateway sending an error MDN similar to the following.

MDN for Message-ID: <123456ABCDEF.acme.com>
From: MY_AS2_PARTNER
To: MY_AS2_STATION
Received on: Mon May 21 23:56:52 UTC 2018
Status: failed
Comment: Message processing failed due to the following errors
Errors encountered :
error: Cannot validate message signers of : <123456ABCDEF.acme.com> - Cause : 
   Trust anchor for certification path not found. - Signers : OU=COMODO SSL, OU=Domain Control Validated
error: Signature verification failure

Note the root cause of the failure:

Trust anchor for certification path not found. - Signers : OU=COMODO SSL, OU=Domain Control Validated

This issue is related to AS2 Gateway not being able to build the trust anchor for the certificate of your partner. In most cases the reason for this would be that your partner’s certificate is signed by a third party and the signer’s certificate is not imported to the AS2 Gateway as a trusted certificate. One such third party which we have encountered in multiple cases is COMODO RSA Domain Validation Secure Server CA (C=GB,ST=Greater Manchester,L=Salford,O=COMODO CA Limited,CN=COMODO RSA Domain Validation Secure Server CA).

Resolution for this would be to add the issuer (signer) certificate, as a trusted certificate. Please make sure to check with your partner to find out the intermediate certificates which need to be imported. Once you have the certificates, first, navigate to Certificates view and then click on the Import Certificates button from the top action pane. This will open a popup where you can pick the certificate files and submit them by clicking on the Import button.

Q: My partner is unable to connect to AS2 Gateway endpoint, in order to send inbound messages.

AS2 Gateway does not block any incoming traffic/IP addresses by default. So, a connectivity issue usually indicates a problem on the partner’s firewall, or an intermediate firewall between them and AS2 Gateway.

Commands like traceroute, when run on the partner’s end, may provide useful details for them to investigate and resolve the issue.

AS2 Gateway allows incoming TCP traffic over the AS2 listener ports (8280, 8443, 4080, 443); however it does not allow UDP or ICMP (e.g. ping) traffic. Your partner cannot check connectivity using commands like ping service.as2gateway.com because such traffic is not accepted; hence, the best way is to use direct TCP connectivity tools, e.g.:

telnet service.as2gateway.com 8280
nc service.as2gateway.com 8280
openssl s_client -connect service.as2gateway.com:8443   # for HTTPS

Q: My partner is getting a TLS/SSL handshake error when trying to send inbound messages.

This could be due to one of many reasons:

Your partner is trying to send messages to the HTTP port (8280) using HTTPS protocol; possibly by configuring a URL with an invalid protocol-port combination (e.g. https://service.as2gateway.com:8280/…)
Your partner’s system does not trust the service.as2gateway.com:8443 HTTPS certificate (CN=*.as2gateway.com). They can either import the certificate into their trusted certificate stores, or try one of the alternative HTTPS ports (4080 or 443) which offer certificates that are ultimately issued by DST Root CA X3 - a more commonly trusted certificate authority (CA).
(Less likely:) Your partner is trying to negotiate a set of TLS/SSL algorithms, protocol version, key length etc., that AS2 Gateway does not allow/support.

In either case, it is recommended to first establish connectivity using HTTP (via http://service.as2gateway.com:8280/service/as2-receiver) - which will eliminate any TLS/SSL factors.

AS2 protocol already includes end-to-end payload encryption via partner certificates, and verification (integrity checks) via digital signatures. You gain very little additional advantage by using HTTPS on top, in exchange of a fairly high processing and transmission overhead. Unless you or your partner absolutely require HTTPS for compliance reasons, it is strongly recommended to use HTTP for both inbound and outbound AS2 messages.

If HTTPS is essential, and above remedies do not resolve the HTTPS/TLS level issues, contact support for further assistance.

Q: My partner is getting an `HTTP 422: Unprocessable Entry` error response when sending a message to AS2 Gateway.

This error generally occurs due to a small misconfiguration of the partner type. AS2 Gateway has two endpoints for incoming messages with one endpoint generally used for testing and the other being used for production. Which URL to use also depends on the partner type in the partner configuration. If you have set the partner type as TEST then you’ll have to use the test endpoint URL (http://test-service.as2gateway.com:8280/service/as2-receiver) and if you have set the partner type as PROD you’ll have to use the prod endpoint URL (http://service.as2gateway.com:8280/service/as2-receiver) when sending messages to the AS2 Gateway.

Q: Failing to decrypt the incoming message and the AS2 Gateway sending an error MDN containing the following message.

Decryption failure : Expected AS2 message for recipient with certificate serial number : 1234567890123456 
issued by : CN=www.acme.com,O=acme solutions,OU=None,L=None,ST=None,C=None which is the local identity. 
However, the received message was intended for : Serial number : 17716044148874147374 issued by 
C=LK,ST=Some-State,O=AdroitLogic,OU=AS2-Gateway,CN=as2gateway.org,E=info@adroitlogic.com, with error code 
800 : Generic error, No payload in AS2 message, with error code 1100 : Generic error

The issue occurs when your partner has configured an incorrect encryption certificate for messages that are being sent to you. One common case we have encountered over the years is that sometimes the partner may mistakenly use the AS2 Gateway HTTPS certificate (which is also included in the partner configuration sharing email) as your encryption certificate. The sample error given above demonstrates such a scenario. You’ll need to check with your partner to rectify this issue.

Q: Failing to decrypt the incoming message with reason “Error getting keypair” and the AS2 Gateway sending an error MDN.

Decryption failure : Error getting keypair for alias acme_alias-123456123456 from identity keystore

This error can occur if you uploaded a keystore during the AS2 station creation, providing a wrong password for the Key Password field. You can perform the following steps to verify this:

First, download the JKS file for your station, from the Certificates view.
Then use the command keytool -export -alias acme_alias-123456123456 -file cert.crt -keystore identity.jks to export the certificate from the key store.
Once you run the above command, your certificate will be exported to a file called cert.crt.
Navigate to the file’s location and try opening the file.
Provide the password when prompted. Note that if a password is not prompted, it means the certificate does not have a password set.
Most probably, you’ll notice a mismatch of the password.

If so, you’ll have to upload the keystore again, providing the correct password, to rectify the issue. You can do these as follows.

First, navigate to the Stations view.
Find the particular station you are having the issue with and click on “Manage Station” button.
Then scroll down to the “Keystore” section and toggle the “Upload Existing Key Store” to true.
There you can fill in the details and upload the keystore again. More information on uploading a new keystore can be found here in the quick start guide.
Once the form is correctly filled click on “Save”.