FUSE issues

Troubleshooting FUSE-specific problems and compatibility

The FUSE (Filesystem in Userspace) mount method allows TorBox Media Center to create a virtual filesystem that appears as if files are stored locally. This guide covers FUSE-specific issues and their solutions.

Operating system compatibility

FUSE support varies by operating system. TorBox Media Center checks your platform at startup and will exit if FUSE is not supported.

Windows is not supported

FUSE mounting is not supported on Windows. If you attempt to run with MOUNT_METHOD=fuse on Windows, you’ll see this error:

The FUSE mount method is not supported on Windows. Please use the STRM mount method or run this application on a Linux system.

From main.py:22-24:

if platform == "win32":
    logging.error("The FUSE mount method is not supported on Windows. Please use the STRM mount method or run this application on a Linux system.")
    exit(1)

Solution: Use MOUNT_METHOD=strm instead, which is compatible with all operating systems.

Supported operating systems

OS	FUSE Support	Notes
Linux	✅ Yes	Fully supported, FUSE comes pre-installed on most distributions
macOS	✅ Yes	Requires macFUSE to be installed
BSD	✅ Yes	Supported on most BSD variants
Windows	❌ No	Not supported, use STRM method instead

From the README: “Compatibility is limited to Linux/Unix/BSD based systems when using the fuse option due to requiring FUSE.”

Installing FUSE

If FUSE is not already installed on your system, follow these instructions.

Linux (Debian/Ubuntu)

sudo apt-get update
sudo apt-get install -y fuse libfuse-dev

Linux (RHEL/CentOS/Fedora)

sudo yum install -y fuse fuse-devel

macOS

Install macFUSE from macfuse.github.io:

brew install --cask macfuse

After installation, you may need to approve the system extension in System Preferences > Security & Privacy.

Verify installation

Check if FUSE is installed:

which fusermount

Expected output:

/usr/bin/fusermount

Read-only filesystem

The FUSE mount is intentionally read-only. You cannot modify, rename, or delete files through the mount.

Why read-only?

From the README troubleshooting section:

The Fuse mount is not meant to be editable, it is read-only. You cannot rename files, delete files, or move them around. This is by design as this software handles that.

File permissions

Files are mounted with read-only permissions (0o444):

From fuseFilesystemFunctions.py:178:

st.st_mode = stat.S_IFREG | 0o444  # Read-only file

Directories are mounted with 0o755 permissions (read and execute for all, write only for owner, but writes are blocked):

From fuseFilesystemFunctions.py:171:

st.st_mode = stat.S_IFDIR | 0o755

Write operations are blocked

Any attempt to write will return an access error:

From fuseFilesystemFunctions.py:196-199:

def open(self, _, flags):
    accmode = os.O_RDONLY | os.O_WRONLY | os.O_RDWR
    if (flags & accmode) != os.O_RDONLY:
        return -errno.EACCES  # Access denied

Solution: To delete or modify files, use your TorBox account at torbox.app. Changes will be reflected in the mount after the next refresh.

Docker requirements for FUSE

Running FUSE inside Docker requires additional configuration.

Required: SYS_ADMIN capability

FUSE requires the SYS_ADMIN capability to create filesystem mounts:

cap_add:
  - SYS_ADMIN

From the README example:

services:
  torbox-media-center:
    # ... other config ...
    cap_add:
      - SYS_ADMIN
    security_opt:
      - apparmor:unconfined

Without this capability, you’ll see errors like:

fuse: failed to open /dev/fuse: Operation not permitted

Required: /dev/fuse device

The /dev/fuse device must be mapped into the container:

devices:
  - /dev/fuse:/dev/fuse

Without this device, you’ll see:

fuse: device not found, try 'modprobe fuse' first

Required: Security options

Disable AppArmor restrictions:

security_opt:
  - apparmor:unconfined

This allows the container to perform privileged operations required for FUSE.

Complete Docker Compose example

From the README:

name: torbox-media-center
services:
  torbox-media-center:
    container_name: torbox-media-center
    stdin_open: true
    tty: true
    restart: always
    volumes:
      - /path/to/torbox:/torbox
    devices:
      - /dev/fuse:/dev/fuse
    environment:
      - TORBOX_API_KEY=<YOUR_KEY>
      - MOUNT_METHOD=fuse
      - MOUNT_PATH=/torbox
    cap_add:
      - SYS_ADMIN
    security_opt:
      - apparmor:unconfined
    image: anonymoussystems/torbox-media-center:latest

Common FUSE errors

Error: Transport endpoint is not connected

ls: cannot access '/torbox': Transport endpoint is not connected

Cause: The FUSE mount has crashed or been unmounted unexpectedly.

Solution: Restart the container:

docker restart torbox-media-center

If the issue persists, manually unmount and restart:

# Unmount
sudo fusermount -u /path/to/torbox

# Restart container
docker restart torbox-media-center

Error: fuse: failed to open /dev/fuse

fuse: failed to open /dev/fuse: Operation not permitted

Cause: Missing SYS_ADMIN capability or /dev/fuse device.

Solution: Add the required Docker configuration:

devices:
  - /dev/fuse:/dev/fuse
cap_add:
  - SYS_ADMIN
security_opt:
  - apparmor:unconfined

Error: fusermount: mount failed: Operation not permitted

fusermount: mount failed: Operation not permitted

Cause: Insufficient permissions or missing FUSE module.

Solution:

1. Ensure FUSE kernel module is loaded:

   sudo modprobe fuse
   lsmod | grep fuse
   

2. Check user permissions:

   groups $(whoami) | grep fuse
   

3. If not in the fuse group, add yourself:

   sudo usermod -a -G fuse $(whoami)
   

4. Log out and log back in for group changes to take effect.

Error: Directory not empty

fuse: mountpoint is not empty
fuse: if you are sure this is safe, use the 'nonempty' option

Cause: The mount directory contains files or a previous mount is still active.

Solution: The nonempty option is automatically added on Linux (from fuseFilesystemFunctions.py:276-279):

if platform != "darwin":
    server.fuse_args.add(
        "nonempty"
    )

If you’re running locally (not in Docker), ensure the directory is empty:

rm -rf /path/to/torbox/*

Or manually unmount any existing mount:

sudo fusermount -u /path/to/torbox

Unmounting FUSE

If you need to manually unmount the FUSE filesystem:

fusermount -u /path/to/torbox

From fuseFilesystemFunctions.py:294-300, this is automatically handled on shutdown:

def unmountFuse():
    try:
        os.system("fusermount -u " + MOUNT_PATH)
    except OSError as e:
        logging.error(f"Error unmounting: {e}")
        sys.exit(1)
    logging.info("Unmounted successfully.")

The application handles cleanup when stopped normally (Ctrl+C or docker stop).

FUSE vs STRM: When to use which

From the README compatibility section:

Use FUSE when...

• You’re using Plex, VLC, Infuse, or other players that don’t support .strm files
• You’re on a Linux, macOS, or BSD system
• You need files to appear as if they’re stored locally
• You have sufficient system resources (FUSE is more resource-intensive)

Use STRM when...

• You’re using Jellyfin or Emby (which support .strm files natively)
• You’re on Windows
• You want better compatibility and simpler setup
• You have limited system resources
• You’re running into FUSE permission or capability issues

From the README: “If you are unsure, choose the strm option.”

Performance considerations

Caching

FUSE implements a block-based cache to improve performance:

From fuseFilesystemFunctions.py:147-149:

self.cache = {}
self.block_size = 1024 * 1024 * 64  # 64MB Blocks
self.max_blocks = 64  # Max 64 blocks in cache (4GB)

This means up to 4GB of file data can be cached in memory.

Link caching

Download links are cached for 3 hours to reduce API calls:

From fuseFilesystemFunctions.py:26:

LINK_AGE = 3 * 60 * 60  # 3 hours

After 3 hours, links are refreshed automatically.

Resource usage

From the README:

The virtual filesystem created by the fuse mounting method can be slower (playing files, reading files, listing files and directories) and take up more resources as it emulates an entire filesystem.

If performance is an issue, consider:

• Using the STRM method instead
• Increasing the refresh interval to reduce API calls
• Allocating more memory to the Docker container

Still having issues?

If you continue to experience FUSE-related problems:

1. Check the common issues guide
2. Review the Docker permissions guide
3. Check your system logs: dmesg | grep fuse
4. Enable debug logging and check container logs: docker logs -f torbox-media-center
5. Contact support at [e-mail]