Troubleshooting | Zerobyte Docs

This guide covers common issues and their solutions. Before troubleshooting, enable debug logging to get more detail.

Enable Debug Logging

Add LOG_LEVEL=debug to your environment variables and restart:

environment:
  - LOG_LEVEL=debug

Then view logs:

docker logs -f zerobyte

Never share sensitive information (passwords, access keys, personal data) in public issue reports. Redact them from logs before posting.

Container Won't Start

Check logs: docker compose logs zerobyte
Verify APP_SECRET is set and at least 32 characters
Ensure /var/lib/zerobyte exists and has correct permissions
Verify port 4096 is not already in use: netstat -tuln | grep 4096

Permission Issues

If you encounter permission errors on the data directory:

sudo chown -R 1000:1000 /var/lib/zerobyte

Remote Mount Issues

Permission Denied When Mounting

Mounting remote filesystems requires kernel-level privileges. Ensure:

Remote share credentials are correct
The host kernel supports the target filesystem (e.g., CIFS module is available)
Docker is running in rootful mode (rootless Docker cannot perform kernel mounts)
Your container has SYS_ADMIN capability:
```
cap_add:
  - SYS_ADMIN
```

Alternative: Mount on Host

If container-level mounting causes issues, mount the remote share on the host first, then bind-mount it into the container:

# Mount on host
sudo mount -t cifs //server/share /mnt/your-remote-share -o credentials=/path/to/creds

# Then in docker-compose.yml
volumes:
  - /mnt/your-remote-share:/data

Security Framework Issues

Linux security frameworks may block mount operations even with SYS_ADMIN. Try these solutions in order:

Check if AppArmor is blocking mounts:

sudo aa-status
docker inspect --format='{{.AppArmorProfile}}' zerobyte

If it returns docker-default, disable AppArmor for the container:

security_opt:
  - apparmor:unconfined

Docker's default seccomp profile may block mount-related syscalls:

security_opt:
  - seccomp:unconfined

Adjust the SELinux context:

security_opt:
  - label:type:container_runtime_t

Or disable SELinux enforcement for the container:

security_opt:
  - label:disable

Last resort: If nothing else works, you can run with privileged: true. This disables most container isolation and should only be used temporarily for diagnosis.

FUSE Mount Failures

FUSE-based mounts (SFTP volumes, rclone volumes) require /dev/fuse:

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

Verify FUSE is accessible inside the container:

docker exec zerobyte ls -la /dev/fuse

/dev/fuse is not required for SMB/CIFS or NFS mounts, only for SFTP and rclone volumes.

Rclone Issues

Test on Host First

Before reporting rclone issues, verify rclone works on your Docker host:

# List configured remotes
rclone listremotes

# Test listing a remote
rclone lsd myremote:

# Test reading files
rclone ls myremote:path/to/test

If these commands fail on the host, fix your rclone configuration first. Common causes:

Expired OAuth tokens, run rclone config to re-authenticate
Incorrect credentials
Missing permissions on the cloud provider side
Network or firewall issues

Zerobyte can't find your rclone configuration. Check:

docker exec zerobyte ls -la /root/.config/rclone/

Ensure the config is mounted:

volumes:
  - ~/.config/rclone:/root/.config/rclone:ro

For non-root containers, set the correct path:

environment:
  - RCLONE_CONFIG_DIR=/home/appuser/.config/rclone
volumes:
  - ~/.config/rclone:/home/appuser/.config/rclone:ro

Restart the container after mounting the config.

"Failed to Create File System" Error

Usually an authentication failure. On your host:

Run rclone config and re-authenticate the remote
Verify with rclone lsd remote:
Restart the Zerobyte container

SFTP Repository Authentication Failures

If your rclone SFTP remote uses key_file, the path points to the host filesystem which isn't accessible inside the container.

Solutions:

Mount SSH keys: ~/.ssh:/root/.ssh:ro
Embed key in config: Use key_pem instead of key_file
Use ssh-agent: Set key_use_agent = true and mount the SSH agent socket

See the rclone guide for detailed instructions.

Rclone Volume Mount Errors

Rclone volumes (mounting cloud storage as a data source) require:

Linux host (Windows/macOS cannot use rclone volumes)
/dev/fuse device mounted
SYS_ADMIN capability

"fusermount3: Permission denied": Verify /dev/fuse is mounted and check for AppArmor/seccomp restrictions.

"Operation not permitted": Add SYS_ADMIN capability.

Backup Issues

Restore Fails with `lchown` or `operation not permitted`

If you restore directly to SFTP, SMB, WebDAV, rclone, or another mounted filesystem, the destination may accept file contents but reject ownership, mode, timestamp, or xattr updates.

See Restoring Data for the full restore workflow, the explanation, and the safest workarounds.

Backup Failed: Permission Denied

Ensure the volume directory has proper permissions:

sudo chmod -R 755 /path/to/your/data

Backup Running Slowly

Check network bandwidth (for cloud repositories)
Check disk I/O performance
Enable compression for large compressible files
Adjust parallel upload settings in repository configuration
Consider bandwidth limits if other services are affected

Repository Locked

If you see "repository is locked" errors, a previous operation may have been interrupted. Use the Unlock button in the repository settings.

Only unlock if you're certain no other backup or restore operations are running against the repository.

Getting Help

If you've tried the solutions above and still have issues:

Enable debug logging (LOG_LEVEL=debug)
Collect relevant logs: docker compose logs --tail=200 zerobyte
Open an issue at github.com/nicotsx/zerobyte/issues

Include in your report:

Zerobyte version (visible in the UI footer)
Docker and Docker Compose versions
Relevant logs (with sensitive data redacted)
Steps to reproduce the issue

On this page