Troubleshooting¶

Common problems with the Valkey cache, what causes them and how to fix them.

`NOAUTH Authentication required`¶

Cause: the client connected without a user name and password. The default user is off.

Fix: authenticate as cache with the password from /etc/valkey/credentials/cache.password, or use sudo /opt/sushi/bin/valkey-cache-cli.

`WRONGPASS invalid username-password pair`¶

Cause: the password does not match the hash in /etc/valkey/users.acl, often after a rotation that changed only one of the two files.

Fix: rotate again with the procedure in Rotate the password, which updates both together.

`NOPERM` errors¶

Cause: the key does not start with cache:, or the command is in a denied category, such as FLUSHALL, CONFIG, RENAME or pub/sub commands.

Fix: prefix your keys with cache: and use data commands only. To clear the cache, restart Valkey.

Plaintext connections fail¶

Cause: the client is not using TLS. Port 6379 accepts TLS connections only.

Fix: turn on TLS in your client (rediss://, or --tls for valkey-cli) and trust /usr/local/share/sushi/valkey/ca.pem.

Certificate verification fails from another host¶

Cause: the server certificate created on first boot covers only localhost and 127.0.0.1.

Fix: issue a certificate that includes the private address, see Issue a server certificate for a private address.

`EVAL` reports a missing scripting engine¶

Cause: this build does not include Lua scripting.

Fix: move the logic into your application.

Keys disappear¶

Cause: either Valkey restarted (persistence is off), or the cache reached its 1536 MiB cap and evicted the least recently used keys.

Fix: this is expected for a disposable cache. Refill keys from your source of truth, or raise the cap on a larger instance, see Change the memory cap.

Valkey does not start after first boot¶

Cause: the first-boot service stopped because the TLS files are incomplete, the certificate and key do not match, or the certificate is not signed by the CA. It does not overwrite existing files to repair this.

Fix: read the reason, then restore the matching files from your backup or rotate the complete set, see Rotate the TLS certificates:

sudo journalctl -u sushi-valkey-firstboot --no-pager
sudo systemctl restart sushi-valkey-firstboot
sudo systemctl start valkey

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

Troubleshooting¶

NOAUTH Authentication required¶

WRONGPASS invalid username-password pair¶

NOPERM errors¶