Troubleshooting
What to do when an agent does not connect, does not search, or returns an error.
The agent does not connect
The agent is connected, but it does not use ByteRover
The search runs, but the result is not what you expect
Error codes
A failed tool call returns two pieces of text. The first is JSON with an error object, and the second is one line, code: message, for agents that read only text.
| Field | In | Meaning |
|---|---|---|
code | Every error | One of the codes below. |
message | Every error | What went wrong, in words. |
search_id | search errors that come from the search itself | The ID of the failed search, at the top level of error. Give it to support. |
drive_ids | search errors with drive_unavailable | The drives that can't be searched right now. |
retryable | list, read, write, upload and download errors | true when the same call can work later. |
retry_after_ms | list, read, write, upload and download errors | How long to wait before trying again, or null. |
operation_id | list, read, write, upload and download errors | An ID for the failed operation, or null. |
details | list, read, write, upload and download errors | More facts about the error, such as the field that was wrong. |
| Code | What it means | What to do | Try again? |
|---|---|---|---|
invalid_request | An input is missing or wrong. | Read the message and fix the input. | Not without a change |
unauthenticated | The sign-in has ended. | Let the agent start the sign-in again, and select Allow. | After signing in |
forbidden | Your role or the connection's permissions don't allow this, or you have no drives. An update to a file in a drive that you can read but not write is forbidden too: the drive is read-only for this connection. | Read the message. See Some errors in detail. Don't try another drive. | No |
not_found | The document or drive doesn't exist, or you can't see it. A drive you can't see looks the same as one that doesn't exist. A source read also gives it for a revision that isn't stored, or for a stored file that is missing. | Read the message. Check the ID, or search again to get a current one. | No |
conflict | A change in progress got in the way of the search or read, or a read named a revision that isn't the one in the index. | Read the message: repeat the call, or read without revision. | Yes, or after the change |
rate_limited | Too many calls in a short time. | Wait as long as the error says, then repeat the call. | Yes, after the wait |
balance_exhausted | The team's balance can't pay. A search is refused when the balance is below the price of the search. A save is refused when the file would take the team past its free storage and the balance has no money left. | Tell the person. A team owner or admin adds money on the Billing page. | After the balance has money |
search_unavailable | Search can't run right now. | Repeat the search with the same effort. | Yes |
drive_unavailable | A drive, or a service that a call needs (storage, the file queue or sign-in), can't be reached right now. This can happen with search, list, read, write, upload or download. | Wait a short time, then repeat the same call. | Yes |
timeout | The search took too long. | Repeat the search at the same effort. Use a lower effort only if the person agrees. | Yes |
internal | An unexpected error in ByteRover. | Repeat the call once. If it fails again, send the search_id to support. | Once |
Two rules apply to agents. Keep the effort the person chose: after an error, repeat the call at that effort, and ask the person before you lower it, even when the message suggests a lower effort. And don't treat an error as a reason to look for more access: forbidden is an answer, and the agent shouldn't try to work around it.
Some errors in detail
When the team's balance is below the price of a search, the search is refused with balance_exhausted until a team owner or admin adds money. See Pricing and billing.
Get help
Give support the search_id of the search that went wrong. You'll find it in every search result and in any error that comes from the search itself. Support can use it to find the search without you sending your question or your files.