Troubleshooting¶

Common problems with the NATS broker, what causes them and how to fix them.

`Permissions Violation`¶

Cause: the user tried to publish or subscribe on a subject it is not allowed to use. For example, publisher may publish only on sushi.pilot.>.

Fix: use a subject the user is allowed, or change its permissions, see Users and permissions.

Authorization fails¶

Cause: wrong user name or password, or the password file and the bcrypt hash in nats-server.conf no longer match.

Fix: check which password your client uses. If you changed a password, make sure you updated the hash too, then check and restart, see Change a password.

The subscriber gets nothing¶

Cause: Core NATS delivers at most once. A message published while no subscriber is connected is dropped, not stored.

Fix: start the subscriber first. If you need stored messages, Core NATS is not the right fit.

Requests time out¶

Cause: the responder is not subscribed, or one side is not allowed to use _INBOX.>. The requester must be allowed to subscribe to _INBOX.>, and the responder to publish to it.

Fix: check both users' permissions.

TLS errors from a client¶

Cause: the client does not trust the instance's CA, does not use TLS, or connects by an address the certificate does not cover. The certificate created on first boot covers only localhost and 127.0.0.1.

Fix: use a tls:// URL, give the client /usr/local/share/sushi/nats/ca.pem, and for a private address issue a certificate that includes it, see Issue a server certificate for a private address.

NATS does not start after a configuration change¶

Cause: the configuration has an error.

Fix: check it and read the log:

sudo nats-server -t -c /etc/nats/nats-server.conf
sudo journalctl -u nats-server -n 50 --no-pager

NATS does not start after first boot¶

Cause: the first-boot check found the identity incomplete: the configuration exists but a certificate, key or password file is missing or empty. It does not regenerate part of an identity, because the existing hashes and certificates would no longer match.

Fix: restore a consistent backup of /etc/nats/, then retry:

sudo journalctl -u sushi-nats-core-firstboot --no-pager
sudo systemctl restart sushi-nats-core-firstboot
sudo systemctl start nats-server

If it still fails, contact info@softwaresushi.com.