Why are my push notifications with images failing to deliver, sometimes with a 'Message Too Big' error?

Push notification services have a hard limit on the size of a notification's payload: 4096 bytes for both Apple's Push Notification service (APNs) and Firebase Cloud Messaging (FCM). If the payload is bigger, the push service rejects the message and it is never delivered.

In the sending report the rejection appears as MessageTooBig ("Message size exceeds the 4096 bytes FCM limit") for Android, Chrome and Firefox, and as PayloadIsTooLarge ("The message size exceeds 4096 bytes") for iOS, macOS and Safari.

A common cause for this issue is embedding large data directly into the push payload, such as including a full image encoded in Base64 format. Long Custom Data JSON and very long links add up to the same limit.

To resolve this, you should follow the best practice for sending rich media in push notifications:

1. Host the image externally. Upload it to the Pushwoosh Media store, or to a server where it is accessible via a public URL.
2. Include the image URL in the payload. Enable the Media content toggle in the push preset and paste the direct URL to the image instead of the image data itself.

By sending a lightweight URL instead of the heavy image data, you keep the payload well under 4096 bytes, ensuring your notifications are delivered successfully. See Sending errors for the full list of error codes.