Troubleshooting

command not found: mass-ctl

Ensure the mass-client package is installed on the client machine. Verify with:

mass-ctl --version

If the package is installed but the command is not found, open a new login shell — the package adds /opt/boostx-sds/bin to PATH through /etc/profile.d.

Mount fails with "permission denied"

• Run mass-ctl login to obtain a valid certificate, or use a machine certificate with --cert / --key / --ca
• Verify your identity is Active in the Dashboard under Identity & Access → Users & Groups or Machines
• Check that an access policy grants the permissions you need on the target volume, under Identity & Access → Access Rules
• If the policy changed while the volume was mounted, remount — permission changes reach an existing mount only after a remount

Certificate expired

Run mass-ctl login again. Machine certificates are long-lived and rarely expire; to reissue one, run sudo mass-ctl machine register again on the host.

Mount hangs, or fails naming a subnet mismatch

The client host needs a network card on the storage network's subnet. mass-ctl stops immediately with an error naming the mismatch rather than hanging until a connection timeout.

• Confirm the client is connected to the storage fabric
• Confirm the interface has an address on that subnet
• On a host with several network cards whose primary address is off the storage network, the client selects the correct card automatically — if it cannot, the error names the network it tried to reach

Mount returns input/output errors after a restart

Established mounts recover on their own when a node's storage service restarts — the mount is re-armed so the next access works. You do not need to reboot the client. If errors persist, unmount and mount again.

Mount did not come back after a reboot

Reboot recovery is registered by default. Check that the mount was not created with --no-fstab, which is explicitly temporary. Non-root registration goes through a helper installed with the package, so confirm the package was not partially removed.

Low throughput after mount

• Run eval $(mass-ctl env --bandwidth) in the shell before starting the workload
• Confirm the fabric is running the transport you expect — Hardware → Network shows a Fabric Protocol chip (RDMA or TCP)
• For Ethernet fabrics, confirm jumbo frames (MTU 9000) are configured end to end, including the switch
• On a multi-socket host, the client already picks the closest network card automatically

dsync fails at launch

The MPI runtime it needs ships with the package. On hosts running Mellanox OFED a compatible MPI is selected automatically. If you have your own MPI installation you want to use, pass --mpi-prefix.

Verbose output

Add --verbose, or raise the log level:

mass-ctl --log-level debug mount --volume-id <id> -m /mnt/data