Errors & troubleshooting
Recognize a failed connection, recover safely, and avoid duplicate launches.
REST error shape
HTTP status describes the class of failure; the JSON error code is the more specific signal. Retry creation with the same Idempotency-Key when retrying the same request.
{
"error": {
"code": "session_limit",
"message": "The tenant concurrent session limit has been reached."
}
}Common failures
| Status / code | Meaning | Next step |
|---|---|---|
| 400 · invalid_options / invalid_viewer_options | Unsupported fields or invalid values | Check integer ranges and field names. |
| 401 · unauthorized | Missing, invalid, or revoked API key | Check Authorization: Bearer and the dedicated client key. |
| 401 · invalid_viewer_link | Invalid, expired, or revoked signed link | Ask the owner to mint a new link. |
| 403 · read_only | The key cannot perform this action | Use a Browser control key only if control is intended. |
| 403 · workspace_suspended / trial_exhausted | Workspace access or allowance is restricted | Check usage and the dashboard. |
| 404 · not_found | No accessible session or route | Verify ID, workspace key, and endpoint path. |
| 409 · idempotency_conflict | An ID was reused with different launch options | Keep options unchanged for retries; use a new ID for a new launch. |
| 409 · already_connected / controller_connected | An external controller conflicts with this operation | Disconnect the existing controller before connecting or using MCP page actions. |
| 409 · viewer_limit | Eight viewers are already connected | Close an existing dashboard or standalone viewer, then reconnect. |
| 410 · session_gone | Browser ended or expired | Create a new session with a new request ID. |
| 413 · body_too_large / image_too_large | Input or output exceeds its bound | Reduce the request or screenshot workload. |
| 422 · browser_action_failed / element_not_found | The target could not be acted on | Refresh the snapshot and select a visible, enabled element. |
| 429 · session_limit / creation_rate_limit / provider_capacity | Concurrency, rate, or shared capacity limit | Respect Retry-After; close unused sessions. |
| 502 · provider_unavailable / browser_disconnected | The browser backend or connection failed | Inspect session state; retry carefully and close unused sessions. |
MCP is not connecting
Check that the URL is exactly https://tabfleet.com/, with no /mcp suffix or API key in its query. The client must support Streamable HTTP with OAuth or an API-key Authorization header. If you want OAuth, remove any manually configured API-key header so the client can start authorization.
An ordinary browser visit returning 401 is expected. GET/DELETE 405 is expected for this stateless transport; the client should use POST. Fully restart the client after configuration changes so it rediscovers tools.
If using an environment variable, ensure it exists in the environment that launches the client. A desktop app may not inherit variables from your shell. Check MCP isError results even when HTTP status is 200.
The iframe is blank or refuses to load
Confirm the exact parent origin is in viewer_embedding_settings. HTTPS, port, and hostname must match. Each ancestor frame must be allowed. Generate a new viewer URL after changing the allowlist.
The browser session and signed URL must both still be active. If eight viewers are already connected, close one before opening another. A view-only link cannot scroll or navigate the remote page; request control only when intended.
A screenshot does not appear in my chat
The screenshot tool returns an MCP image content block. Whether it appears inline depends on the MCP client. Tabfleet does not turn screenshots into hosted image URLs. A client may save the returned image or expose it as a downloadable attachment instead.
The session is still closing
A 202 response means cleanup is pending. Poll GET /v1/sessions/:id and check usage. The reservation remains held until cleanup is confirmed; do not repeatedly launch replacement browsers while cleanup or capacity is unresolved.