# Troubleshooting

## Connection issues

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

1. Both peers need IPv6. Test at [test-ipv6.com](https://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:
```bash
# Install macFUSE from https://macfuse.github.io/
# Restart your Mac after installation
```

Linux (Debian/Ubuntu):
```bash
sudo apt install fuse3
```

Linux (Fedora):
```bash
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:
```bash
sudo sh -c 'echo "user_allow_other" > /etc/fuse.conf'
```

Linux:
```bash
# 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 **KEIBI**DROP).

### 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 **KEIBI**DROP crashes and the mount point is stale:

macOS:
```bash
sudo /sbin/umount -f /path/to/mount
```

Linux:
```bash
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)

```bash
xcode-select --install
```

### CGO errors (macOS)

```bash
export CGO_ENABLED=1
xcode-select --install
```

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

### CGO errors (Linux)

```bash
export CGO_ENABLED=1
sudo apt install build-essential
```

### Rust build fails with missing `libkeibidrop.a`

Build the Go static library first:
```bash
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:
```bash
make build-static-rust-bridge
cd rust && cargo build --release
```

If you want to regenerate protobuf stubs:

macOS:
```bash
brew install protobuf
make install-proto
make protoc
```

Linux:
```bash
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](https://winfsp.dev/) (2.1 or later recommended); the mount appears as a drive letter, and the mount point must not already exist.