Troubleshooting

This covers how to troubleshoot issues that may arise with the on-premise WhatsApp API.

Phone Number Change Notification

Users using v2.47 series will not be getting notifications about changes in phone number even if they have this setting enabled.

Affected version:

• Whole v2.47 series

Fix:

• This issue is addressed on the latest v2.49.1 release. Please upgrade to this version for the fix.

Country Restrictions

Businesses in Cuba, Iran, North Korea, Syria, and three sanctioned regions in Ukraine (Crimea, Donetsk, Luhansk) are not eligible to use the WhatsApp Business Platform.

WhatsApp Messenger (WhatsApp) and WhatsApp Business app users in Cuba, Iran, North Korea, Syria, and three sanctioned regions in Ukraine (Crimea, Donetsk, Luhansk) are not eligible to receive messages sent via the WhatsApp Business Platform.

Unable to send messages with emojis

Messages with emojies might fail with QSqlError("1366", "QMYSQL: Unable to execute query", "Incorrect string value: '...' for column 'data' at row 1")

Affected Versions:

• All

Possible fix:

• Make sure the libmariadb-dev version is 1:10.3.37 or less inside CoreApp container.
• Avoid upgrading packages inside the CoreApp, Web containers. Please follow the instructions to upgrade.

Failed with exec: "launch_within_docker.sh": cannot run executable found relative to current directory

Affected Versions:

• v2.45.1, v2.43.2, v2.43.1, v2.41.3

Possible Fixes (any of the following):

1. For GCP, Azure & AWS Ensure you are using latest templates with CMD override.
2. Downgrade containerd.io < 1.6.18.
3. Update to unaffected versions: v2.43.3, v2.45.3, v2.45.2.
4. Override the CMD for container startup.
   • How you do this will vary based on your setup.
   • Use /opt/whatsapp/bin/launch_within_docker.sh as the execution path / CMD.

Failed with exec: socket failed: Address family not supported by protocol and web pod fails

Affected Versions:

• v2.45.3, v2.47+

This can happen if the ipv6 networking stack is completely disabled in your environment.

Fix:

1. Set the environment variable ENABLE_IPV6 to false on the webapp container.

WABA Admin Unable to Download Certificate

Follow these steps:

• Verify that the WABA account is approved by going to Business Manager > Business Settings > Accounts > WhatsApp Accounts > Find the WABA you want to download the certificate for > Settings:
  1. If your account is approved but you still cannot download the certificate, contact support.
  2. If your account has not been approved, please wait a week and check again then.

Cannot Create Certificate

If you are not able to create a certificate for your phone number, and you see this error in the Whatsapp Manager, it is because the phone number is already in use:

Once a number has been registered with an API client, it cannot be deleted then re-added.

If you believe that this is an error and the phone number has not actually been registered, please contact support.

The quickest solution would be to add a new, previously unregistered phone number.

Offline Phone Number Status in WABA but not Flagged for Quality

If your phone number status is showing as "Offline" in WABA, but it was not flagged for quality, it is likely that your docker instance has stopped running due to insufficient resources. You will need to restart your docker containers. Additionally, you should ensure that your container configuration has the minimum recommended core parameters.

Troubleshoot Your Client

• Use the WADebug command line tool to help find any potential issues with the WhatsApp Business API setup and to make requesting help from WhatsApp support more effective.

• Collect logs from all containers

~/biz $ docker-compose -f docker-compose.yml -f network-waent.yml logs > debug_output.txt

• Collect the logs of a specific service, append the service name (waweb or wacore) to the docker-compose logs command:

~/biz $ docker-compose -f docker-compose.yml -f network-waent.yml logs waweb > debug_output.txt

You can find the logs in the debug_output.txt file in the current directory.

Media Upload Errors

While trying to upload media by URL using the /media endpoint, or trying to send a media message using the link param, you may receive the following error message via webhooks:

{
   "statuses": [
       {
           "errors": [
               {
                   "code": 500,
                   "title": "Media upload error (Connection closed)"
               }
           ],
           "id": "gBEGkZdCkJYlAgloe7nahJW35zc",
           "recipient_id": "16315555555",
           "status": "failed",
           "timestamp": "1617349703"
       }
   ]
}

If you get that error, it may be because:

• The server hosting the file rejected the request from Webapp.
• The server hosting the file is not reachable.
• The proxy in-between Coreapp and server has terminated the connection.

How To Fix It

1. Check server logs from the server hosting the file.
2. Verify your docker container can reach the media server by making Curl request from within the container:

docker exec <webapp-container-id> curl -X GET  <url-of-file> > file.pdf

Secure Socket Layer (SSL) Errors

If you are unable to upload or download media or if your webhooks are not being delivered to your call back URL, you may see some of the following messages in your log entries:

• Webhook contains network error "SSL handshake failed".
• Fatal SSL error: "The certificate is self-signed, and untrusted."
• Error code: QNetworkReply::SslHandshakeFailedError
• "Request for url failed with error: SSL handshake failed"

If you get these errors, it may be because:

• Your certificate may not have a proper chain.
• Your certificate may be self-signed, and that is not permitted for calls to the /media endpoint.
• If you are using an Internal CA (self-signed), it is possible that this certificate was not used to generate the webhook’s certificate.

How To Fix It

1. Confirm the SSL handshake works using the curl tool: curl -X POST -H 'Content-type: application/json' --data '{"text":"Hello World!"}' --cacert <CERTIFICATE_PEM_FILE> <WEBHOOK_URL>. The certificate file should be the same that was uploaded to the Enterprise Client. You can download the certificate from Enterprise Client by following the steps here.
2. [Step only used for media upload or download issues] Verify certificate chain is complete: openssl verify -verbose cert.pem
3. Delete cert, re-upload the cert, and restart the Coreapp.

WhatsApp Business API v2.35 includes more extensive logging around media upload and download issues. On v2.35 you can look for the following entries in your logs: "MediaUploader: Found %d ssl errors" and "MediaDownloader: Found %d ssl errors".