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:

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

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

Change:

"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:

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. chmods 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

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 for how host/port/user/pass are set, and Architecture for protocol details.