Troubleshooting and console keys

Troubleshooting#

• The phone says the certificate doesn't match. The server's key changed (config directory lost, or a new --tls-key): pair again.
• `license_required` in the app. The server is Unlicensed or Locked: open the License tab. See Server license.
• `device_limit` when pairing. Your plan allows 3 paired devices: revoke one on the Devices tab.
• The server won't start: “can't decrypt identity.enc”. The key doesn't match the store: restore the right KUBYL_SERVER_KEY or credentials.key. See Credentials and sign-ins.
• The web UI asks for a token on the server's own machine. You reached it through a proxy or a host name that isn't localhost or an IP: use the admin token or open https://localhost:8443/.
• A cluster shows “sign-in required” or is greyed out. With per-device sign-ins, sign in on the device, or list the cluster under shared_contexts. See Credentials and sign-ins.
• The app says “Not verified” and lists no clusters. The server could not prove its license (too old to have the lease capability, or no valid lease for this install). Update the server image and check the License tab. See Settings and the license screen.
• Locked with `clock_rollback`. The server's clock is more than 10 minutes behind its last lease. Fix the date and time (check NTP in the container host), then press N on the License tab.
• The server won't start: the config directory is readable by others, or `credentials.key` is. It refuses both. Run chmod 700 on the directory and chmod 600 on the key.
• A store file was renamed to `….undecryptable-<time>`. No key opened it; the server moved it aside rather than overwrite it. Restore the matching key or lease, or sign in to clusters again.
• No metrics or “No metrics source”. The server found neither Prometheus nor metrics-server on that cluster. See Metrics, alerts and flows.
• Helm install and upgrade buttons are missing. The server has no usable helm (3.13 or newer), Helm writes are switched off, or the cluster is read-only. Calls then answer FAILED_PRECONDITION with the reason. See What the mobile client can and cannot do.
• An agent shows “broken” or “needs sign-in”. See AI agents: goose needs GOOSE_PROVIDER and GOOSE_MODEL, and a key the provider refuses turns the agent to needs-sign-in at the first prompt.
• A Copilot agent fails to start. /config is mounted noexec; Copilot unpacks a native add-on there.
• Pushes don't arrive. The server must be Licensed or in Grace and able to reach the relay (https://kubyl.dev/api/push); try More, Notifications, Test. Online activation and push both fail with UNREACHABLE when the server has no route to kubyl.dev.
• The sign-in browser fails with two devices at once. Browser sign-ins use fixed loopback ports on the server; use the device-code sign-in or take turns.
• “too many reveals; wait a minute”. Reveals of Secret values are rate-limited per device.

Console keys#

Tab and Shift Tab or 1 to 4 switch tabs, ? lists the keys, Q quits (it asks first).

Windows smaller than 60x20 show “make the window larger”. Without a terminal, kill -USR1 <pid> prints a new pairing code to stdout.