DiscoverVulcain | Server Push Web APIs
Mercure.rocks

Contribute!

Troubleshooting

401 Unauthorized

  • Double-check that the request to the hub includes a mercureAuthorization cookie or an Authorization HTTP header
  • If the cookie isn't set, you may have to explicitly include the request credentials (new EventSource(url, {withCredentials: true}) and fetch(url, {credentials: 'include'}))
  • Check the logs written by the hub on stderr, they contain the exact reason why the token has been rejected
  • Be sure to set a secret key (and not a JWT) in JWT_KEY (or in SUBSCRIBER_JWT_KEY and PUBLISHER_JWT_KEY)
  • If the secret key contains special characters, be sure to escape them properly, especially if you set the environment variable in a shell, or in a YAML file (Kubernetes...)
  • The publisher always needs a valid JWT, even if the anonymous directive is present in the Caddyfile, this JWT must have a property named publish. To dispatch private updates, the publish property must contain the list of topic selectors this publisher can use (example)
  • The subscriber needs a valid JWT only if the anonymous directive isn't present in the Caddyfile, or to subscribe to private updates, in this case the JWT must have a property named subscribe and containing an array of topic selectors (example)

For both the publish property, the array can be empty to publish only public updates. For both publish and subscribe, you can use ["*"] to match all topics.

Browser Issues

If subscribing to the EventSource in the browser doesn't work (the browser instantly disconnects from the stream or complains about CORS policy on receiving an event), check that you've set a proper value for cors_origins in the Caddyfile. It's fine to use cors_origins * for local development.

URI Templates and Topics

Try our URI template tester to ensure that the template matches the topic.

Mac OS Localhost Installation Error

How to process for Mercure to work in Mac OS Catalina:

  • In the Finder on your Mac, locate the app that you want to open
  • Control-click on the app icon, then choose "Open" from the shortcut menu
  • Click "Open"

Then you will have a warning, ignore it and close the Terminal.

Open a new Terminal in the Mercure folder.

Then just start the server:

./mercure run

It will work. 🎊