# 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](mcp-tools.md). |

## 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](mailto: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.