Common issues

Quick diagnostics for the problems seen most often when bringing up or running a LeilFS cluster. For log locations and how to read them, see Logs and logging; for first‑line health checks, see Basic checks.

---

Chunkserver cannot connect to the master

• Verify MASTER_HOST and MASTER_PORT in leil-chunkserver.cfg (the master's chunkserver port is 9420).
• Check firewall rules on both the master and the chunkserver.
• Confirm the chunkserver can resolve the master's hostname (e.g. leil-master) — LeilFS recommends /etc/hosts over DNS (see Network setup).
• Look in the master log for connection‑refusal messages (journalctl -u saunafs-master).

---

Files stuck in an under-replication state

• Run leil fileinfo <path> to see how the file's chunks are distributed.
• Confirm enough chunkservers are online to satisfy the file's goal — an EC or copies goal needs at least as many chunkservers as it has parts (see Replication).
• Check for disks near the HDD_LEAVE_SPACE_DEFAULT threshold — a full disk cannot receive new copies.
• If replication is simply slow, temporarily raise CHUNKS_WRITE_REP_LIMIT on the master.

---

Mount fails with "connection refused"

• Verify the master is running: systemctl status saunafs-master.
• Check that the master's client port (MATOCL, default 9421) is reachable from the client.
• Confirm the client's IP is permitted in leil-exports.cfg (see Access control).
• If the export requires a password, supply it — -p to prompt, or -o sfspassword=....