# Daemon: setup & troubleshooting

If `transtui` can't connect at startup, and `host` points at the local
machine (`127.0.0.1`/`localhost`), it tries to help automatically - what
happens depends on *why* the connection failed.

## Case 1: No daemon responds at all

You're asked:

> No daemon is responding at 127.0.0.1:9091. Start transmission-daemon?

If you answer `y`, `transmission-daemon` is launched (must be in `PATH`)
and `transtui` tries to connect for a few seconds while it starts up.

**If `transmission-daemon` isn't installed**, you instead get a clear error
message with an install hint:

```sh
sudo apt install transmission-daemon     # Debian/Ubuntu
```

(on other distributions a generic pointer to your package manager is shown,
e.g. `dnf install transmission-daemon` on Fedora).

## Case 2: The daemon responds but requires a password you don't know (HTTP 401)

Very common if you installed via `apt`: Debian's package starts
`transmission-daemon` as a **systemd service** right at install time, with
RPC authentication enabled and a **randomly generated password** that's
never shown in plaintext anywhere. There's no way to "read back" that
password afterward.

`transtui` detects this specifically (distinguishes "no daemon responding"
from "daemon responds with 401") and asks:

> The daemon at 127.0.0.1:9091 is responding but requires a password we
> don't know. Fix it now (requires sudo)?

If you answer `y` you get to choose:

- **Set a custom password** - you enter a password, `transtui` sets
  `rpc-username` to `transmission` and that password in the daemon's
  config, and saves the same credentials in your own `config.ini` so the
  next run connects automatically.
- **No** (disable password protection entirely) -
  `rpc-authentication-required` is set to `false`. Convenient if you run
  everything locally on your own machine and don't care about access
  control on the RPC port.

How it's done technically: `transtui` reads
`/etc/transmission-daemon/settings.json`, only changes the affected fields
(via JSON parsing, no text manipulation), writes the result to a temp
file, then runs `sudo systemctl stop transmission-daemon`,
`sudo cp <tempfile> /etc/transmission-daemon/settings.json`, and
`sudo systemctl start transmission-daemon` as three separate commands (no
shell involved), so your password can never accidentally be interpreted as
a shell command regardless of what characters it contains. The `sudo`
prompt appears in the same terminal `transtui` is running in.

### Manually, if you'd rather do it yourself

```sh
sudo systemctl stop transmission-daemon
sudo nano /etc/transmission-daemon/settings.json
```

Change:

```json
"rpc-authentication-required": true,
"rpc-username": "transmission",
"rpc-password": "YourPassword",
```

(or set `rpc-authentication-required` to `false` to disable password
protection entirely). Save, then restart:

```sh
sudo systemctl start transmission-daemon
```

Transmission hashes the password in the file automatically the next time
the daemon starts - that's expected, not a bug.

## Case 3: A torrent errors with "permission denied" on its download directory

Very common when the daemon was installed via `apt`: Debian's package runs
`transmission-daemon` as its own system account (`debian-transmission`), not
as you. If you point a torrent at a folder only your user owns - e.g. your
own `~/Downloads`, which defaults to mode `0700` - the daemon can create the
torrent but can't write any data into it, and the torrent sits in an error
state with an `errorString` like:

```
Couldn't create '/home/you/Downloads/...': Permission denied
```

The first time `transtui` sees a torrent error containing "permission
denied" (and the daemon is local, and *your* user genuinely can write to
that directory - so this really is just an account mismatch, not a missing
folder), it asks:

> '\<torrent>' can't write to '\<dir>' (permission denied) - looks like the
> daemon's service account can't get into a directory only your user owns.
> Fix it now (requires sudo)?

If you answer `y`, `transtui`:

1. Looks up the directory's owning group and runs
   `sudo usermod -aG <that group> debian-transmission`.
2. `chmod`s the directory group-writable (no `sudo` needed - you already own
   it).
3. Restarts the daemon via `sudo systemctl restart transmission-daemon`,
   since group membership only takes effect for processes started after the
   change.
4. Retries the torrent that errored.

This is offered at most once per session (whether you accept or decline),
so a torrent still failing for some other reason won't re-prompt on every
poll.

### Manually, if you'd rather do it yourself

```sh
sudo usermod -aG "$(stat -c '%G' ~/Downloads)" debian-transmission
chmod g+rwx ~/Downloads
sudo systemctl restart transmission-daemon
```

## Triggering the help again later

The connection flows (cases 1 and 2) can be triggered again: open settings
(`g`) and press `r` when the title shows "not connected". The download
directory fix (case 3) isn't tied to that key - just restart `transtui`,
which resets the once-per-session offer.

## Other common errors

| Symptom | Likely cause |
|---|---|
| `Connection error: cannot connect to host:port: Connection refused` | No daemon is listening on the given host/port - see above for `127.0.0.1`, otherwise check that the remote daemon is running and the port is reachable (firewall?) |
| `HTTP error 401 from server` (in the status line, without the auto-help appearing) | Host isn't `127.0.0.1`/`localhost` - can't be auto-fixed on a remote machine, set `-u`/`-p` or edit the settings manually with the right credentials |
| `RPC error: ...` | The daemon responded but the RPC call failed for another reason - the text after the colon comes directly from Transmission's own error reporting |
| `could not parse JSON response` | Unusual - check that `host`/`port` actually point at a Transmission daemon and not something else that happens to respond on that port |

See also [Configuration](Configuration.md) for how host/port/user/pass are
set, and [Architecture](Architecture.md) for protocol details.