Troubleshooting

Work through the checks in order. Most problems resolve at riby status.

First check: riby status

riby status

Healthy output shows the server URL, your agent name, and the pending-request count. What it tells you:

• Server is not reachable: a network problem, or the server URL is wrong. If you use a custom server, verify it with riby status --server-url <url>.
• Run 'riby login' first.: this machine has no credentials. Run riby login.
• Login expired or revoked. Run 'riby login'.: your token was revoked (for example from the dashboard) or has expired. Log in again.

The CLI exits with code 2 when authentication is the problem, which makes it easy to script around.

The agent says authentication required

The MCP server returns Authentication required. Run 'riby login' for <server-url> when it starts without credentials. Log in with the CLI, then restart the MCP server (in most harnesses, restarting the session is enough).

Pages are not arriving

1. Run riby status. If the pending count is nonzero, the request was created and the problem is delivery, not the agent.
2. Open runitby.you and check the request inbox. The dashboard is always a channel; if the request shows there, your channel linking is the issue.
3. Check Channels on the dashboard. If Telegram is not listed as linked, link it: Channels, then Link Telegram. Linking flows for both Telegram and Discord are in the channels guide.
4. In Telegram, send /status to the Riby bot. It replies with your link state and any pending pages.

The Telegram link code failed

That link is invalid, expired, or already used. means the one-time code is dead. Create a fresh link from runitby.you, Channels. Codes are single-use and short-lived by design.

Linking only works in a private chat with the bot, not in a group.

The agent crashed while waiting

The request did not die with it. It lives in the local append-only ledger and on the server. When the agent restarts, have it call the check_pending tool: it reconciles the ledger and returns every request with its current status, including answers that arrived while the agent was down.

A request expired

Expiry is deny. If you did not answer within the TTL (6 hours by default), the agent received Denied by timeout. This is deliberate: no answer never becomes silent permission. If six hours does not fit your schedule, change the TTL in the dashboard settings, from 1 hour up to 24.

Two channels answered at once

Only the first answer counts. Resolution is atomic on the server, so a Telegram tap and a dashboard click cannot double-resolve a request. The losing channel's message updates to show the winning resolution.

I cannot tell my agents apart

Every page carries an instance label, folder · branch by default. If you run many instances from the same folder, set RIBY_SESSION_NAME per instance to name them explicitly.

Still stuck

Log out and back in to reset credentials on the machine:

riby logout
riby login

If the problem survives that, it is probably ours. [PLACEHOLDER — support contact email or issue link.]