Skip to content

Troubleshooting

gitsync edited this page Oct 4, 2026 · 5 revisions

Portal won't start

Binary exits immediately

sudo journalctl -u zfsnas -n 50
Symptom Cause Fix
address already in use Port 8443 is taken Change the port in config/config.json or stop the conflicting process
permission denied on config/ Wrong file ownership sudo chown -R zfsnas:zfsnas /opt/zfsnas/config
TLS cert not found config/certs/ missing The portal auto-generates certs — ensure the config/ directory is writable
cannot bind port < 1024 Running without root on a privileged port Use port 8443+ (default) or set CAP_NET_BIND_SERVICE

Portal is running but unreachable

  • Verify the service is listening: ss -tlnp | grep 8443
  • Check firewall rules: sudo ufw status or sudo iptables -L
  • Verify you are using https:// not http://

Setup wizard loop

If the portal keeps redirecting to /setup after creating the admin account:

  1. Check that config/users.json was written: cat /opt/zfsnas/config/users.json
  2. Verify the zfsnas user has write permission: sudo -u zfsnas touch /opt/zfsnas/config/test && rm /opt/zfsnas/config/test
  3. Check for disk full: df -h /opt/zfsnas

Login fails

Symptom Cause Fix
"Invalid username or password" Wrong credentials Double-check; reset via direct JSON edit if locked out
2FA code rejected Clock skew Sync system clock: sudo timedatectl set-ntp true
Session not persisting Cookie blocked Check browser cookie settings; ensure you are using HTTPS
Rate limited Too many failed attempts Wait 60 seconds and try again

Admin account locked out

If you have lost the admin password and cannot log in, edit config/users.json directly on the server and replace the password_hash value with a new bcrypt hash:

# Generate a new bcrypt hash for "newpassword"
python3 -c "import bcrypt; print(bcrypt.hashpw(b'newpassword', bcrypt.gensalt(12)).decode())"

# Edit users.json
sudo -u zfsnas nano /opt/zfsnas/config/users.json

ZFS operations fail

zpool / zfs commands fail with permission errors

The portal runs ZFS commands with sudo. Check:

# Verify sudo is working for the zfsnas user
sudo -u zfsnas sudo zpool list

# Check the sudoers file
sudo visudo -c -f /etc/sudoers.d/zfsnas

Common problems:

Error Fix
sudo: command not found sudo apt-get install sudo
sudo: zfsnas is not in the sudoers file Add the whitelist entry from Security
zpool: command not found sudo apt-get install zfsutils-linux
ZFS module not loaded sudo modprobe zfs

Pool is DEGRADED / SUSPENDED / reports device errors

Use the Pool Fixer Wizard — it appears automatically in the ZFS Pools page header whenever a pool needs attention, explains what happened in plain language, and proposes the fix (clear errors, bring disks online, or guided disk replacement):

Pool Fixer Wizard

Pool shows as UNAVAILABLE after reboot

Encrypted pools need their keys loaded before they can mount. The portal does this automatically at startup — if it fails:

  1. Check that config/keys/ contains the key file
  2. Verify the key file is readable by zfsnas: sudo -u zfsnas ls -la /opt/zfsnas/config/keys/
  3. Manually load the key: sudo zfs load-key -L file:///opt/zfsnas/config/keys/<keyfile> <pool>

SMB shares not accessible

Service won't start

sudo systemctl status smbd
sudo journalctl -u smbd -n 50
# Test config file
sudo testparm /etc/samba/smb.conf

Clients can't connect

Check Command
Service running systemctl is-active smbd
Listening on port 445 `ss -tlnp
Firewall sudo ufw allow samba
SMB password set sudo pdbedit -L (should list the user)

Permission denied when accessing files

If files inside are restricted, check effective permissions:

namei -l /data/myshare

NFS shares not accessible

Mount fails on client

# Check server exports
showmount -e <server-ip>

# Test connectivity
nmap -p 2049 <server-ip>
Problem Fix
rpcbind not running sudo systemctl start rpcbind
Firewall blocks NFS Allow ports 111, 2049
Client IP not in export Check the client CIDR in NFS share settings

SMART data not showing

Symptom Fix
No temperature displayed Some drives don't expose temperature via SMART; check with sudo smartctl -a /dev/sdX
smartctl: command not found sudo apt-get install smartmontools
NVMe temperature missing sudo apt-get install nvme-cli
All fields empty SMART may be disabled on the drive; enable with sudo smartctl -s on /dev/sdX

Alerts not sending

Email

  1. Click Test in Settings → Notifications → Email
  2. Check the portal logs for SMTP errors: sudo journalctl -u zfsnas | grep -i smtp
  3. Common issues:
Error Fix
connection refused Wrong SMTP host or port
authentication failed Wrong username/password; check if app passwords are required
TLS handshake error Try switching TLS mode (none/starttls/tls)
Mail delivered to spam Add SPF/DKIM records for your sending domain

ntfy / Gotify / Pushover

  1. Verify the server URL is reachable from the NAS
  2. Check that the token/key is correct
  3. Send a test notification and check the portal log

Binary update fails

Problem Fix
permission denied replacing binary Ensure the zfsnas user owns /opt/zfsnas/zfsnas
Download stalls Check outbound HTTPS to GitHub from the server
Service doesn't restart Check sudo systemctl restart zfsnas works manually
Version shows as downgrade Downgrade is blocked by design; this is expected behavior

MinIO (S3) issues

The S3 server can no longer be installed on new systems (MinIO stopped publishing its open-source binaries); alternatives are under evaluation. See S3 Object Storage.

Problem Fix
Service fails to start Check /var/log/syslog; verify the dataset is mounted and has enough free space
mc commands fail Ensure the service is running; check server URL in Configure
TLS certificate errors If TLS is enabled, use https:// in client config and trust the cert
Bucket access denied Verify IAM user is enabled and policy is attached
Data directory permissions sudo chown -R minio-user:minio-user <data-dir>

UPS not detected

# Manual scan
sudo nut-scanner -C -N    # USB only (fast)
sudo nut-scanner -a -t 2  # All methods (slower)

# Check USB device visibility
lsusb | grep -i ups
dmesg | grep -i hid

Performance issues

Portal is slow to respond

  • Check system load: uptime
  • Check disk I/O: the top bar sparklines show current utilization
  • Check memory: free -h — ZFS ARC should consume available RAM; this is normal

ZFS read performance is poor

  • Check ARC hit rate: ZFS Pools → Cache Config → ARC Level 1 (Memory) shows the hit/miss ratio
  • If hit rate is low, consider adding an L2ARC device (fast SSD) — see ZFS Pools
  • Verify compression is enabled: zfs get compression <dataset>

ZFS write performance is poor

  • Check if sync is set to always on the dataset — switch to standard if not needed
  • Consider adding a ZIL (SLOG) device for synchronous workloads

Log locations

Log Location Purpose
Portal audit log config/audit.log All portal actions
Portal system log journalctl -u zfsnas Startup, errors, debug output
Samba log /var/log/samba/ SMB connections and errors
NFS log journalctl -u nfs-server NFS mount/unmount events
ZFS events zpool events Pool and disk events from the kernel
MinIO log journalctl -u minio S3 server events
NUT log journalctl -u nut-server UPS daemon events

USB appliance

Boot, persistence, upgrade and serial-console issues specific to the appliance are covered in USB Appliance → Troubleshooting.


Getting help

Clone this wiki locally