# MAM (MyAnonaMouse) Troubleshooting Reference

## Tracker Error: "Unrecognized host/PassKey"

**Full error from MAM's tracker detail page:**
```
ip          port   agent                 error
181.214.x.x 36590  -qB5230- / 5.2.3     Unrecognized host/PassKey. (181.214.x.x)
```

**Root cause:** Browser IP ≠ torrent client IP. MAM compares the IP you're browsing
from against the IP your torrent client is announcing from. When they don't match
(e.g., browser on home connection, torrent client on VPN), the passkey is rejected
even though the passkey itself and the client version are valid.

**MAM FAQ reference:**
> *"If you are running your client over a VPN, but not your browser (or browser is
> on a different vpn tunnel), such as a docker container that also runs the vpn,
> you'll first need to be approved to use a VPN by staff (per rule 1.2). Then
> you'll want to use the Dynamic Seedbox endpoint to manage the client on a
> non-matching IP."*

**Resolution:**
1. Get staff approval via MAM ticket system
2. Set up [Mousehole](https://github.com/t-mart/mousehole) to call the Dynamic
   Seedbox API: `https://www.myanonamouse.net/api/endpoint.php/3/json/dynamicSeedbox.php`

## Tracker Error: "Non-Whitelisted client or version"

**Bencoded tracker response:**
```
d8:intervali86400e12:min intervali86400e8:retry ini86400e14:failure reason58:Non-Whitelisted client or version https://s.mrd.ninja/CLNTe
```

**Check the allowed clients page:** https://s.mrd.ninja/CLNTe

**qBittorrent status on MAM:**
- Allowed: from 5.0.1 to latest 5.2.x line (confirmed as of 2026-07-09)
- qBittorrent Anonymous Mode IS rejected by MAM
- Peer ID format: `-qB5230-` for 5.2.3 on non-Windows
- User-agent: `qBittorrent/5.2.3`

**Known caveat:** The tracker-level whitelist filter may lag behind the web page.
If a new version is on the web whitelist but still getting rejected, there may be
a propagation delay.

## Fastresume Fields (via `strings`)

Key fields in `.fastresume` files that matter for troubleshooting:

| Field | Meaning |
|---|---|
| `paused` | 0 = active, 1 = paused |
| `disable_dht` | 0 = DHT enabled (should be 1 for private trackers) |
| `num_complete` | seeders count, 16777215 = sentinel (unknown) |
| `num_incomplete` | leechers count, 16777215 = sentinel (unknown) |
| `total_downloaded` | bytes downloaded so far |
| `active_time` | seconds the torrent has been active |
| `last_seen_complete` | 0 = never seen a complete copy |
| `last_download` | 0 = no downloads |

Ben code sentinel value 16777215 (0xFFFFFF) means "no data" — the tracker hasn't
returned peer information.

## Dynamic Seedbox API

- **Endpoint:** `https://www.myanonamouse.net/api/endpoint.php/3/json/dynamicSeedbox.php`
- **Requires:** Valid MAM session cookie
- **Purpose:** Registers the current IP of the calling client as an authorized
  seedbox IP for the user's account
- **Frequency:** Called periodically by Mousehole (handled automatically once
  configured)

### Docker Compose Patterns

### Adding Mousehole as a sidecar to existing gluetun + qBittorrent

Required changes to an existing docker-compose.yml:

1. **Gluetun ports:** add `- 127.0.0.1:5010:5010` (or `- 5010:5010` for LAN/KasmVNC access)
2. **Gluetun environment:** add `,5010` to `FIREWALL_VPN_INPUT_PORTS`
3. **New service:** add the mousehole service with `network_mode: "service:gluetun"`
4. **New volume:** add a `mousehole:` volume for cookie persistence

The mousehole service does NOT need to communicate with qBittorrent — it only
talks to the MAM API. It shares gluetun's network stack so outbound traffic goes
through the VPN tunnel.

### Docker Port Binding

When `docker compose restart` doesn't pick up compose file changes:

```
# This restarts with OLD config:
docker compose restart gluetun

# This recreates with NEW config:
docker compose up -d gluetun
```

To verify what ports are actually bound:
```
docker port gluetun
```

`127.0.0.1:5010` binding means host-only. If accessing from KasmVNC or another
Docker container, the port must bind to 0.0.0.0 (specify just `5010:5010` in
compose without an IP prefix).