Skip to content
flexFS

Common Issues

Mount Failures

Section titled “Mount Failures”

”mount point is already mounted” (flock)

Section titled “”mount point is already mounted” (flock)”

Another mount.flexfs process holds the mount lock for this mount point. This typically means a daemon is already running.

Solution: Check for existing processes with ps aux | grep mount.flexfs. If the mount is stale, see the stale mount section below.

”mount point is not empty and —nonEmpty flag has not been set”

Section titled “”mount point is not empty and —nonEmpty flag has not been set””

The target directory contains files or subdirectories.

Solution: Either empty the directory or add the --nonEmpty flag (or nonEmpty in fstab options).

“invalid mount point: does not exist”

Section titled ““invalid mount point: does not exist””

The mount point directory does not exist.

Solution: Create the directory: mkdir -p /mnt/flexfs.

”invalid admin addr: empty”

Section titled “”invalid admin addr: empty””

The credentials file is missing or does not contain an adminAddr field.

Solution: Run mount.flexfs init creds --adminAddr <addr> to initialize credentials, or verify the credentials file at the path shown in the error.

”invalid volume token: empty” or “invalid volume token: not a UUID”

Section titled “”invalid volume token: empty” or “invalid volume token: not a UUID””

The volume token is missing or malformed in the credentials file.

Solution: Re-run mount.flexfs init creds with a valid volume token.

FUSE Errors

Section titled “FUSE Errors”

”/dev/fuse: No such file or directory”

Section titled “”/dev/fuse: No such file or directory””

The FUSE kernel module is not loaded.

Solution:

Terminal window
sudo modprobe fuse

For persistent loading, add fuse to /etc/modules-load.d/fuse.conf.

”fusermount: command not found”

Section titled “”fusermount: command not found””

The FUSE3 userspace tools are not installed.

Solution:

Terminal window
# Debian/Ubuntu
sudo apt install fuse3


# RHEL/CentOS
sudo yum install fuse3

Stale Mounts

Section titled “Stale Mounts”

”Transport endpoint is not connected”

Section titled “”Transport endpoint is not connected””

This indicates a stale FUSE mount where the daemon process has died. The mount.flexfs start command detects this and attempts automatic cleanup.

Solution: If automatic cleanup fails, manually unmount:

Terminal window
sudo fusermount -u /mnt/flexfs
# or
sudo umount -f /mnt/flexfs

Then remount normally.

Mount appears in /proc/mounts but is not responding

Section titled “Mount appears in /proc/mounts but is not responding”

Solution: Force unmount and remount:

Terminal window
sudo fusermount -u /mnt/flexfs
sudo mount.flexfs start <name> /mnt/flexfs

Or use update.flexfs --force to perform a full hard reset of all mounts.

SSL/TLS Errors

Section titled “SSL/TLS Errors”

”x509: certificate signed by unknown authority”

Section titled “”x509: certificate signed by unknown authority””

This occurs when connecting to a server using a self-signed certificate and the client does not trust it.

Solution: Use curl -k or configure the system trust store. For flexFS components, SSL is handled automatically via auto-generated certificates.

”tls: failed to verify certificate”

Section titled “”tls: failed to verify certificate””

Similar to the above. If connecting configure.flexfs to an admin server with a custom certificate, ensure the certificate is valid or use the internal --noAdminSSL flag for testing.

Credential Errors

Section titled “Credential Errors”

”creds file already exists” during init

Section titled “”creds file already exists” during init”

Solution: Use --force to overwrite: mount.flexfs init creds --force --adminAddr <addr>

Credentials file not found

Section titled “Credentials file not found”

Solution: Run the appropriate init creds subcommand for the component. The default credential paths are:

  • Mount: ~/.flexfs/mount/creds/<volume-name>
  • Meta: ~/.flexfs/meta/creds
  • Admin: ~/.flexfs/admin/creds
  • Proxy: ~/.flexfs/proxy/creds
  • Configure: ~/.flexfs/configure/creds

Connectivity Issues

Section titled “Connectivity Issues”

Admin server unreachable

Section titled “Admin server unreachable”

Mount clients and metadata servers require connectivity to the admin server.

Solution:

  1. Verify the admin server is running: manage.flexfs status admin
  2. Check network connectivity: curl -k https://<admin-addr>/v1/status
  3. Verify firewall rules allow traffic on port 443 (or the configured --bindAddr port)

Proxy unreachable

Section titled “Proxy unreachable”

When proxy groups are configured but unreachable, mount clients fall back to direct object storage access. This is normal behavior, not an error.

Solution: If you expect proxy acceleration, verify:

  1. The proxy server is running: manage.flexfs status proxy
  2. Network connectivity between mount client and proxy
  3. The proxy group is associated with the volume in the admin server

Performance Issues

Section titled “Performance Issues”

Slow sequential reads

Section titled “Slow sequential reads”

Solution: Ensure block prefetching is not disabled. Check that the metadata server is responsive (monitor via /metrics). Consider increasing the block size for workloads with large sequential reads.

High write latency

Section titled “High write latency”

Solution: For remote object storage, enable local disk writeback caching with --diskWriteback on the mount client. For Enterprise deployments, deploy a proxy group in the same region as the compute.

Service Management

Section titled “Service Management”

Services not starting after reboot

Section titled “Services not starting after reboot”

Solution: Ensure systemd units are enabled:

Terminal window
sudo systemctl enable flexfs-admin.service
sudo systemctl enable flexfs-meta.service

Or use manage.flexfs start to manually start all services.

”this command must be run as root”

Section titled “”this command must be run as root””

Most manage.flexfs and update.flexfs operations require root privileges.

Solution: Use sudo or run as root.