Skip to documentation content

Troubleshooting

Start with the HTTP response and the listener's History. They show whether a request was skipped, accepted by a provider, or failed. They do not confirm that iOS displayed an alert.

The request succeeded, but no alert appeared

  1. Check delivery.sentCount, not just HTTP 200. A disabled listener can return 200 with no accepted sends.
  2. Keep listener enabled on. If it is off, no new History event is written.
  3. Check enabled for this device. When off, this device's events are Muted.
  4. Check the app's Manage action or iOS notification settings. Permission can be off while History still records events as Sent.
  5. Check Focus, notification delivery settings, network access, and the correct receiving device. Try sending a short text message to isolate the problem.

A Sent event means provider acceptance. Network and iOS settings can still prevent or delay an alert.

History is empty or has not updated

Open the correct listener and tap History, then Refresh. Check that you sent to this listener's URL and that listener enabled was on at send time. History belongs to the current device subscription; a newly subscribed device does not inherit another device's past events.

See Listeners and History for the two delivery switches.

A long message is rejected

The API accepts a title up to 120 characters and a body up to 4,096 characters, but those are field limits. They do not guarantee that the complete push fits.

Apple limits a regular notification payload to 4,096 bytes. That includes the title, body, JSON structure, URLs, and routing or avatar metadata. Non-ASCII text and emoji can use several UTF-8 bytes per character. Adding an image or avatar adds URL and metadata bytes, not the image file itself.

Use a short summary and a url to the full report when a message is long. palmpush does not silently cut the body to make it fit.

  • 400: check field lengths, non-empty text, and URL validity.
  • 413: reduce the total payload. If a provider rejected it, History can contain a failed event.
  • 502: read error.message and delivery.errors. Some destinations may already have succeeded; check sentCount before retrying to avoid duplicates.

See the HTTP API for response fields.

Text looks cut off or line breaks are missing

iOS controls the visible area of a compact notification. Expand it or open History to read the stored message. A cropped preview does not mean the API shortened the body.

Encode line breaks as \n in JSON. Avoid replacing them with spaces in the sending script. HTML and Markdown are shown as text rather than rendered.

The image is missing or cropped

  • Use a direct HTTPS JPEG, PNG, or GIF, no larger than 1 MiB, accessible without login or custom headers. Open the URL separately to check that it returns an image instead of an HTML page.
  • Check that the server sends an image content type and that redirects stay HTTPS.
  • An expired or removed file will also disappear from later History views.
  • Expand the notification: iOS can crop the compact thumbnail. In History, tap the image to view it full-screen.
  • If you sent through JavaScript or MCP, images and tap URLs require palmpush 0.3.0 or @palmpush/mcp 0.2.0 or newer. Older versions do not forward these fields. Until you can upgrade, try the direct HTTP image example.
  • For a PWA, update to the 0.2.0 or newer worker, then copy, deploy, and activate it as described in PWA setup. Updating npm alone is insufficient. Notification images also depend on browser support.

Image download failures can leave the text notification intact. A successful send response is not an image-download receipt.

A tap opens the wrong place

Test with a newly sent notification and iOS app version 1.1. Omit url to open its History entry; include url to open a destination. Existing notifications cannot be updated retroactively.

For an app scheme, check that the target app is installed and supports the link. A failed URL launch shows an error and falls back to History. See Links and tap actions for URL requirements.

An avatar is missing

Set the avatar on this device's listener subscription. Another device's choice does not apply here. Send a new message after saving. Removing a subscription also removes its stored avatar. If the avatar cannot be loaded, the message can appear as an ordinary notification.

For camera access, check the app's camera permission in iOS Settings or choose an existing photo. See listener avatars for the full workflow.

Still need help?

Use Support and include your app version, iOS version, steps, and any HTTP status or redacted error message. Do not post your listener token, send URL, or personal image URLs in public feedback.