Troubleshooting

Common issues and how to resolve them.

Messages Not Arriving

Check the basics

  1. Topic name - Topic names are case-sensitive. MyTopic ≠ mytopic
  2. Server URL - Make sure you're using https://app.notifyhero.com
  3. Subscription - Verify you're subscribed to the correct topic

Test with curl

# Send a test message
curl -d "Test message" https://app.notifyhero.com/test-topic

# Poll for messages
curl "https://app.notifyhero.com/test-topic/json?poll=1"

Mobile app issues

  1. Notification permissions - Grant notification permissions in app settings
  2. Battery optimization - Disable battery optimization for the ntfy app
  3. Do Not Disturb - Check DND settings (high priority messages can override)
  4. Instant delivery - Enable for immediate notifications (Android)

Browser issues

  1. Notification permissions - Allow notifications for the site
  2. HTTPS - Most browsers require HTTPS for notifications
  3. Focus - Keep the tab open for real-time notifications

Delayed Messages

Android

Messages may be delayed when the phone is in doze mode. Solutions:

  1. Enable instant delivery - Creates a persistent connection
  2. Disable battery optimization - For the ntfy app
  3. Use high priority - Priority 4-5 messages are delivered faster

iOS

iOS manages background connections strictly. Some delay is normal.

Rate Limiting

Symptoms

  • 429 Too Many Requests error
  • Messages not being accepted

Solutions

  1. Wait and retry - Rate limits reset after a period
  2. Reduce message frequency
  3. Self-host for custom limits

Default limits

  • 60 requests per hour per visitor
  • 100MB attachments per hour per visitor

Authentication Errors

401 Unauthorized

  • Check username/password
  • Check token hasn't expired
  • Verify server requires auth for this topic

403 Forbidden

  • You don't have access to this topic
  • Check your access permissions
  • Contact server admin

Connection Issues

"Connection refused"

  • Server may be down
  • Check the server URL
  • Check firewall settings

"Connection reset"

  • Network instability
  • Try WebSocket instead of SSE
  • Check proxy/firewall settings

Timeouts

  • Slow internet connection
  • Server overloaded
  • Try polling instead of streaming

Attachment Issues

"Attachment too large"

  • Default limit is 15MB per file
  • Self-host for larger limits

"Attachment expired"

  • Attachments are cached temporarily (default 3 hours)
  • Re-upload the attachment

"Too many attachments"

  • Daily bandwidth limit reached
  • Wait for limit reset or self-host

Self-Hosted Issues

Server won't start

  • Check config file syntax
  • Check port availability
  • Check file permissions

Firebase not working

  • Verify Firebase credentials file
  • Check project configuration
  • Ensure billing is enabled

Database errors

  • Check disk space
  • Check file permissions
  • Try clearing the cache file

Debugging

Enable debug logging

ntfy serve --log-level=debug

Check server health

curl https://app.notifyhero.com/v1/health

View raw messages

curl -s "https://app.notifyhero.com/mytopic/json?poll=1" | jq

Getting Help

If you're still stuck:

  1. Check the FAQ
  2. Search GitHub Issues
  3. Ask on Discord or Matrix