Troubleshooting Rukou
Start by asking the connected agent to call rukou_status. Check its organization, workspace, and agent, and whether browsers can start. Open the same workspace in the app.
Connections
| What you see | What to do |
|---|---|
| Waiting for the first connection | Complete the app's sign-in, or make a request using its API key. Creating a key alone does not connect the app. |
| An authentication error | Copy this agent's address from Agents. Sign in again, or check that the client uses a valid key made for that agent. |
| The wrong workspace or agent | Compare rukou_status with the agent you intended to use, then replace the client's MCP configuration with that agent's setup. |
Only rukou_status and rukou_feedback are listed | Browser sessions are not turned on for this connection. Read the status response's browser availability and the notice on Sessions, then contact Rukou support. |
| A page tool is missing | Check the agent's page permissions. Refresh the client's tool list after changing them. |
| An old tool name fails | Refresh the client's MCP tool list and use the current tools and actions. |
Sessions
| What you see | What to do |
|---|---|
starting | Repeat start with the same label after a few seconds to return to the existing session. |
concurrency_limit | Check open sessions across the organization. End one you no longer need before starting another. |
insufficient_credits | Stop sessions you no longer need, then start again. If it continues, contact Rukou support. |
| A tab limit refusal | List the tabs and close one you no longer need, then open the new tab. |
seed_conflict | A running session with that label has a different seed. Use its original seed, choose another label, or wait until it ends. |
help_requested | Open the session, take control of the requested tab, complete the step, and select Release. The agent can withdraw a request if help is no longer needed. |
| A person holds control | Have that person select Release. An owner or admin can use Release teammate when needed. |
| The session ended | Read its stop reason. Start a new session to continue; an extension cannot reopen an ended browser. |
| A page is still loading | Have the agent wait for the needed element with browser_observe and wait_for, then inspect the result. |
| A click's result is uncertain | Inspect the page before repeating an action that could submit, buy, or send something. |
| A recording is unavailable | Check the session's recording status and retention date. Expired or deleted recordings cannot be replayed. |
If a browser repeatedly fails to start, keep its session ID and the returned error code for support. Changing labels repeatedly can create extra pending sessions.
Logins
| What you see | What to do |
|---|---|
| Logins are unavailable | Ask support whether Logins can be enabled for your organization. |
| An approved agent still needs access | Give the specific connection access on Agents or in the login's details, using an approval method that opens the login. |
| A new API key cannot take logins | Use it once for an authenticated request, then return to Agents and give it access. |
| A saved login will not fill | Check the login's allowed sites or sign-in pages, and wait for the actual form to appear. The agent may need to identify its fields explicitly. |
| The website asks for an email or text code | Check the login's Sign-in codes setting. If you must enter it, take control of the tab, enter it, and release control. |
| A saved sign-in cannot be restored | Sign in again with the login and save the new signed-in state before ending the session. |
| An approval method is lost | Use another saved method. If none opens the login, follow recovery and re-enter its sign-in details when asked. |
| An approval email does not arrive | Check the destination shown by the app and your spam folder. Use Send a new code if available. |
Contact support
Use Contact Rukou support in the app, or email hello@rukou.ai. Include the session ID, approximate time and timezone, the error code, and a short explanation of what you expected and what happened. Include a request ID if the failing call supplied one.
Your agent can also submit a browser-tool bug report with rukou_feedback. Leave credentials, codes, private page contents, and screenshots containing secrets out of support reports.