Skip to content

TROUBLESHOOTING.md

Latest commit

 

History

History
177 lines (119 loc) · 3.82 KB

TROUBLESHOOTING.md

File metadata and controls

177 lines (119 loc) · 3.82 KB
Raw

Troubleshooting

Connection issues

"Connection failed" or peers can't find each other

  1. Both peers need IPv6. Test at test-ipv6.com, you need at least 9/10.
  2. The connection is full-duplex: each peer listens on an inbound port and connects to the other's inbound port. Check your firewall allows inbound TCP on both configured ports (defaults: 26431 inbound, 26432 outbound).
  3. Check your router doesn't block IPv6 inbound connections.
  4. Both peers must use the same relay server.

Rate limit errors

The public relay limits requests per IP. Wait a few minutes and try again. For heavy testing, run a local relay.

FUSE issues

"FUSE not detected"

macOS:

# Install macFUSE from https://macfuse.github.io/
# Restart your Mac after installation

Linux (Debian/Ubuntu):

sudo apt install fuse3

Linux (Fedora):

sudo dnf install fuse3

"Permission denied" when opening files from FUSE mount

Other apps (Finder, Preview, file managers) can't access FUSE mounts unless allow_other is enabled.

macOS:

sudo sh -c 'echo "user_allow_other" > /etc/fuse.conf'

Linux:

# Uncomment or add "user_allow_other" in /etc/fuse.conf
sudo sed -i 's/#user_allow_other/user_allow_other/' /etc/fuse.conf

Then remount (disconnect and reconnect, or restart KEIBIDROP).

macFUSE kernel extension blocked (macOS)

Go to System Settings > Privacy & Security and allow the macFUSE extension.

On macOS 15.4+, macFUSE supports the FSKit backend which runs in user space, no kernel extension needed. Enable it in System Settings > macFUSE > Use FSKit.

FUSE mount not cleaning up

If KEIBIDROP crashes and the mount point is stale:

macOS:

sudo /sbin/umount -f /path/to/mount

Linux:

fusermount3 -u /path/to/mount    # normal unmount
fusermount3 -z /path/to/mount    # force (lazy) unmount

Build issues

pthread.h or stdlib.h not found (macOS)

xcode-select --install

CGO errors (macOS)

export CGO_ENABLED=1
xcode-select --install

Go must use clang on macOS. Check with go env CC. If it shows gcc:

export CC=clang

CGO errors (Linux)

export CGO_ENABLED=1
sudo apt install build-essential

Rust build fails with missing libkeibidrop.a

Build the Go static library first:

make build-static-rust-bridge
cd rust && cargo build --release

protoc-gen-go: program not found

The generated code is committed, so you can build without protoc:

make build-static-rust-bridge
cd rust && cargo build --release

If you want to regenerate protobuf stubs:

macOS:

brew install protobuf
make install-proto
make protoc

Linux:

sudo apt install protobuf-compiler
make install-proto
make protoc

Files and logs

Where is the config file?

~/.config/keibidrop/config.toml, created on first run with default values.

Where are log files?

macOS: ~/Library/Logs/KeibiDrop/keibidrop.log

Linux: ~/.local/share/keibidrop/keibidrop.log

Override with the LOG_FILE environment variable or log_file in config.toml.

Where are received files saved?

Default: ~/KeibiDrop/Received/

Override with TO_SAVE_PATH environment variable or save_path in config.toml.

Platform notes

macOS

  • Requires macFUSE for FUSE mode. Works without it in no-FUSE mode.
  • Apple Silicon and Intel both supported.
  • macOS 15.4+ can use the FSKit backend (no kernel extension).

Linux

  • Requires fuse3 and libfuse3-dev (for building from source).
  • Tested on Ubuntu 22.04+ (x86_64).
  • ARM64 Linux support available for CLI binaries.

Windows

Works in both modes. FUSE mode requires WinFsp (2.1 or later recommended); the mount appears as a drive letter, and the mount point must not already exist.