Skip to main content
Version: 0.0.14

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