Troubleshooting
Start with the message beside the affected Agent or Worker. Keep its existing call and profile while diagnosing an interruption.
The local URL rejects my key
Use the full URL printed by the current rulith start process. Its key changes between runs. A bookmark from an earlier process may no longer work.
Do not share the keyed URL in a support ticket. Report the port and error text with the key removed.
The workbench is already running, or the port is in use
Return to the terminal that started Rulith, stop its roles and exit it there. Then start the updated version once. Do not delete a live lock or run another process over the same profiles.
If another application owns the port, choose a different manager port deliberately; do not stop an unidentified process.
The wrong account appears
Choose the other sign-in provider or account on the browser sign-in page before authorizing this computer. A browser's existing Console session can be reused. Check the account name at the bottom left of Rulith after returning.
Changing the browser account does not silently replace an already signed-in local account. Use the local sign-out flow before signing into another one.
A new or re-enabled Agent is missing
Confirm that Console and Rulith show the same account and Console service. Open the local account menu and press Refresh enabled Agents. Check the received-list status and any sync error. Refreshing a tab alone is not a successful directory response.
If the Agent is listed but not ready, select it and finish setup. A saved profile does not mean its Agent process has started.
Setup says “Finishing setup”
Reopen that Agent's setup and use Check again to collect the original attempt. Do not repeatedly issue new credentials. A failed response does not establish that no credential was created.
If its receipt can no longer be confirmed, follow the sign-out or device-revocation path shown in the account view before reconnecting.
I can sign in but cannot chat
Configure Default model, or the selected Agent's Model settings. Verify the provider's model name, API format, endpoint and API key, then start the Agent.
An empty or truncated model response is not a successful turn. Adjust the model setting or request a smaller step. Rulith does not automatically repeat paid calls.
The Worker is running but an Action is unavailable
Check the selected Agent, its Connection, the Source binding, required Tools and resource permissions. A shared computer does not give one Agent access to another's Worker queue.
If a Connection key was replaced, stop that Worker and save the new key using Replace Connection key before restarting.
Configuration remains pending
The installed configuration and the currently effective one can differ. Inspect live Cases and unresolved calls. Finish or explicitly dispose of them through the normal flow, then check again. A stopped local process alone does not close a cloud Case.
A file cannot be read
Start the Worker that holds it. Check the original material, Source binding and delivery permissions for the current model destination. If you changed models, follow any Worker restart and disclosure prompts.
For the document assistant, use a UTF-8 .txt or .md file up to 256 KiB and install Java 25. Preparation steps explain the checker setup.
A call's result is unknown
Do not repeat the write action. Keep the original request and inspect its pending state from the affected Agent's Runtime view or the relevant Case when one exists.
A call can become pending before any Case exists. An empty Cases list therefore does not prove that no unresolved operation remains. Record an outcome only when you have evidence for it; use the supported unknown-disposition procedure when the external result cannot be established.
A checked draft cannot be saved
Open Review checked draft for the exact proposal. It needs a matching certified completed Case. If a previous save lost its response, reopen the review to check for a saved receipt instead of submitting another copy.
Ask for help
Include the Rulith version, the step that failed, the visible error and a sanitized screenshot. Do not include tokens, connection secrets, model API keys, local access URLs or private document contents.