Troubleshooting
What to check when rio does not do what you expect.
This topic is still to be written. It will cover the user-side faults: a setting that does not stick, a shortcut that does not fire, a theme or mode that does not appear after installing, the agent refusing to run, a remote connection that goes quiet, and how to tell a rio bug from a platform quirk.
Check these first
- CAVEATS.md — known rough edges, and behaviour that differs between platforms and window managers, each with its way around. If what you hit is listed, it is known.
- INSTALL.md §7 — Lifecycle, shutdown & troubleshooting,
for deployment faults: stopping things cleanly, a core host missing
tcltls, and the package names each platform wants. - WINDOWS.md — on Windows, how to get an error message out
of
wish, which prints none for an uncaught error.
Messages that already have an answer
| Message | What to do |
|---|---|
rio needs the Tcl package …, which isn't installed on this host | rio checks what it cannot run without before doing anything else. The message names the missing package, the OS package that provides it (tcllib on Debian and the BSDs, tcl-lib on Alpine, and so on), and points at INSTALL.md section 1. Install it and start rio again. |
rio could not start its core | The window starts its own core as a child process, and this one exited or stopped answering. The message names the exact command to run by hand: run it in a terminal and the core's own complaint is right there. A missing dependency is the usual cause. |
certificate not trusted on a repository row | See a certificate that isn't trusted. |
signing key not confirmed on a repository row | Nothing is wrong. It signs with a key you have never confirmed, and rio installs nothing from a repository until you do. Select the row, press Review signing key…, and see confirming a repository's key. |
signing key changed, signature doesn't verify, signature missing, no longer signed, files don't match the signature | Its signature did not check out, so nothing from it is offered. Select the row for the whole sentence, and see when rio refuses a signed repository. A changed key can be reviewed and accepted from that row. |
can't check the signature | A repository whose key you confirmed, and no way to check it: the core's host has no ssh-keygen from OpenSSH 8.0 or newer, or the core itself predates repository signing. Fix that on the core's host, or see repositories rio can't check. |
The agent refused https, naming tcltls and host-name checks | See HTTPS on an older tcltls. A repository says https needs tcltls 1.8 or newer for the same reason: upgrade tcltls on the core's host, use the repository's http:// URL, or turn on the switch in Preferences ▸ Network, which covers both. |
Further reading
- Preferences — every config file, so you can look at, or move aside, the one you suspect.
- Working remotely — what a remote core does and does not change.