Repository navigation
Troubleshooting
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
|
- Verify the service is listening:
ss -tlnp | grep 8443 - Check firewall rules:
sudo ufw statusorsudo iptables -L - Verify you are using
https://nothttp://
If the portal keeps redirecting to /setup after creating the admin account:
- Check that
config/users.jsonwas written:cat /opt/zfsnas/config/users.json - Verify the
zfsnasuser has write permission:sudo -u zfsnas touch /opt/zfsnas/config/test && rm /opt/zfsnas/config/test - Check for disk full:
df -h /opt/zfsnas
| 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 |
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.jsonThe 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/zfsnasCommon 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 |
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):

Encrypted pools need their keys loaded before they can mount. The portal does this automatically at startup — if it fails:
- Check that
config/keys/contains the key file - Verify the key file is readable by
zfsnas:sudo -u zfsnas ls -la /opt/zfsnas/config/keys/ - Manually load the key:
sudo zfs load-key -L file:///opt/zfsnas/config/keys/<keyfile> <pool>
sudo systemctl status smbd
sudo journalctl -u smbd -n 50
# Test config file
sudo testparm /etc/samba/smb.conf| 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) |
If files inside are restricted, check effective permissions:
namei -l /data/myshare# 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 |
| 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
|
- Click Test in Settings → Notifications → Email
- Check the portal logs for SMTP errors:
sudo journalctl -u zfsnas | grep -i smtp - 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 |
- Verify the server URL is reachable from the NAS
- Check that the token/key is correct
- Send a test notification and check the portal log
| 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 |
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> |
# 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- 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
- 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>
- Check if sync is set to
alwayson the dataset — switch tostandardif not needed - Consider adding a ZIL (SLOG) device for synchronous workloads
| 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 |
Boot, persistence, upgrade and serial-console issues specific to the appliance are covered in USB Appliance → Troubleshooting.
- GitHub issues: https://github.com/macgaver/zfsnas-chezmoi/issues
- Include the portal version (visible in the sidebar or About modal), relevant log lines, and the steps to reproduce
Getting Started
Storage
- Dashboard & Monitoring
- Physical Disks
- ZFS Pools
- Datasets & ZVols
- MergerFS
- Snapshots & Protection
- File Sharing — SMB
- File Sharing — NFS
- iSCSI
- S3 Object Storage
- Capacity Trends
- Encryption
- UPS Management
Virtualization
Networking
Administration
Reference