Web Push: Common Issues and Reporting Bugs

When you hit an issue with web push, it can be difficult to debug the issue or
find help. This doc outlines some of the common issues and what you should
do if you've found a bug in Chrome or Firefox.

Before we dive into debugging push, you may be hitting issues with debugging
service workers themselves, the file not updating, failing to register or
generally just unusual behavior. There is an
awesome document on debugging service workers
that I strongly recommend checking out if you are new to
service worker development.

There are two distinct stages to check off when developing and testing web push,
each with their own set of common issues / problems.

Sending a Message: Make sure that sending messages is successful.
You should be getting a 201 HTTP code. If you aren't :

Check for Connection Issues: If the problem is on Chrome, it
may be a connection. See Connection Issues section
for more info.

If you aren't able to send and receive a push message and the relevant sections
in this doc aren't helping debug the problem then you may have found a
bug in the push mechanism itself. In this case, refer to the
Raising Bug Reports
section to file a good bug report with all the necessary information to expedite
the bug fixing process.

One thing I'd like to call out before we start is that Firefox and the
Mozilla AutoPush Service have great errors messages. If you get stuck and
are not sure what the problem is, then test in Firefox and see if you
get a more helpful error message.

The easiest way to support push in both Firefox and Chrome is to supply an
applicationServerKey in the subscribe() call. The down side is that
any discrepancy between your front end and server's keys will result in an
authorization error.

On Chrome + FCM

For Chrome, which uses FCM as a push service, you'll receive an
UnauthorizedRegistration response from FCM for a range of different
errors, all involving the application server keys.

You'll receive an UnauthorizedRegistration error in any of the following
situations:

If you fail to define an Authorization header in the request to FCM.

Your application key used to subscribe the user doesn't match the key used
to sign the Authorization header.

The expiration is invalid in your JWT, i.e. the expiration exceeds 24 hours or
the JWT has expired.

HTTP Status Codes

There are a range of issues that can result in a non-201 response code from a
push service. Below is a list of HTTP status codes and what they mean in relation
to web push.

Status Code

Description

429

Too many requests. Your application server has reached a rate limit with a
push service. The response from the service should include a 'Retry-After' header to
indicate how long before another request can be made.

400

Invalid request. One of your headers is invalid or
poorly formatted.

404

Not Found. The subscription has expired. In this case you
should delete the PushSubscription from your back end and wait for an
opportunity to resubscribe the user.

410

Gone. The subscription is no longer valid and should be removed from your
back end. This can be reproduced by calling `unsubscribe()` on a
`PushSubscription`.

413

Payload size too large. The minimum size payload a push service must
support is 4096 bytes (or 4kb). Anything larger can result in this error.

If the http status code is not in this list and the error message is not
helpful, check the Web Push Protocol
spec to see if the
status code is referenced along with a scenario of when that status code can
be used.

Payload Encryption Issue

If you can successfully trigger a push message (i.e. send a message to a web
push service and receive a 201 response code) but the push event never fires in
your service worker, this normally indicates that the browser failed to
decrypt the message it received.

If this is the case, you should see an error message in Firefox's DevTools
console like so:

To check if this is the issue in Chrome, do the following:

Go to chrome://gcm-internals and click the "Start Recording" button.

Trigger a push message, and look under the "Message Decryption Failure Log".

If there was an issue with the decryption of the payload, you'll see an error
similar to the one displayed above. (Notice the AES-GCM decryption failed
message in the details column.)

There are a few tools which may help debug encryption if this is your issue: