Common Issues

"Connection refused" when mounting

Cause: Server is not running or not reachable.

Solutions:

1. Check if server is running: ps aux | grep ghostfs
2. Verify server is bound to correct address (use 0.0.0.0 for network access)
3. Check firewall allows port 3444

"Authentication failed"

Cause: Invalid username or token.

Solutions:

1. Verify token with ghostfs auth list on server
2. Check username matches exactly (case-sensitive)
3. Token may have expired — create a new one

"Transport endpoint is not connected"

Cause: Connection to server was lost.

Solutions:

1. Unmount with umount -f /mnt/remote
2. Check network connectivity
3. Remount

"Permission denied" on mount

Cause: FUSE permissions issue.

Solutions:

Linux:

sudo usermod -aG fuse $USER
# Log out and back in

macOS:

# Allow kernel extension in System Preferences → Security & Privacy

Slow performance

Cause: Default cache settings may not suit your workload.

Solutions:

For large sequential reads:

ghostfs mount /mnt/remote \
  --read-ahead 16 \
  --prefetch-workers 100 \
  --prefetch-window 40

For write-heavy workloads:

ghostfs mount /mnt/remote \
  --write-back 128

"Operation not permitted" with encryption

Cause: Wrong encryption key or corrupted file.

Solutions:

1. Verify using the same key that encrypted the files
2. Check key file permissions: chmod 600 ~/.ghostfs/encryption.key