# Google Sheets errors

Every Google Sheets failure uses a stable code and links to the matching heading on this page. Use the code and safe status fields for recovery. Never copy an authorization code, OAuth state, token, account or file identifier, spreadsheet query, range, cell value, request body, operation payload, or raw Google response into a log, ticket, prompt, or chat.

## Symptom

A connection flow, metadata check, Tool save, Search rows action, or Add one row action stops. Dashboard management errors use the normal Operade error envelope. OAuth callback failures return a clean Integrations status. Runtime Tool failures use the same code vocabulary in Activity even when there is no HTTP response.

## Cause

Failures fall into configuration, OAuth lifecycle, unsupported target, access, locked capability, quota, bounded-response, temporary-provider, or uncertain-append classes. Operade maps reviewed Google status and reason classes and fails closed for unknown responses instead of exposing provider text.

## Verify

Record only the code, action (`read` or `append`), UTC time, safe HTTP status class, bounded `retry_after_seconds`, and safe Activity display fields. Ask an owner or admin to check connection status and the explicitly selected My Drive spreadsheet. For uncertain appends, Activity may also show an operation reference used only for human reconciliation.

## Recovery

Follow the exact code below. Reads may use a bounded retry for selected temporary failures. Appends are never automatically retried after a timeout, connection loss, 5xx, target mismatch, or malformed success because another request could add a duplicate row. Reconnect and revoke are owner/admin dashboard actions; customer API keys cannot manage Google connections.

## Escalation

Escalate after one controlled recovery still fails, or immediately when an append outcome cannot be established. Include only the safe fields from **Verify**. Remove internal workspace, user, connection, grant, spreadsheet, and file IDs along with all cell content and provider data. See [Google Sheets troubleshooting](/docs/tools/google-sheets-troubleshooting), [Activity](/docs/monitor/transcript-and-activity), and [Support](/docs/reference/support).

## Error code index

### `google_integration_not_configured`

The feature flag is off or required operator settings are incomplete. An operator must finish the rollout runbook; user retries do not repair configuration.

### `google_oauth_cancelled`

The admin cancelled Google consent. Start a new connection only when the admin intends to continue; do not replay the callback.

### `google_oauth_expired`

The single-use OAuth attempt expired, was consumed, or no longer matches the dashboard session. Start again from Integrations.

### `google_oauth_wrong_account`

Add spreadsheet or reconnect used a different Google identity. Repeat the action with the same account that owns the connection.

### `google_oauth_duplicate_account`

That Google account already has a workspace connection. Use **Add spreadsheet** on the existing connection.

### `google_shared_drive_unsupported`

The selected file belongs to a Shared Drive, which V1 does not support. Choose a My Drive file or wait for a supported rollout.

### `google_file_unavailable`

The grant, connection, file, or provider permission is unavailable. Restore access, add the file again, or reconnect the same account.

### `google_sheet_reconfigure_required`

The saved tab, range, or header snapshot no longer matches. Clone the Tool, review its fixed target and mapping, test it, attach it, and publish a new Agent version.

### `google_tool_locked`

An immutable Agent version captured this Google Sheets Tool. Use **Clone to change**; Google capabilities cannot be edited or deleted after publish.

### `google_quota_exceeded`

A local limiter or Google quota rejection blocked the action. Wait for `retry_after_seconds`, then make one controlled retry without parallel requests.

### `google_response_too_large`

Metadata, provider content, or Tool output crossed an enforced safety bound. Narrow the fixed range, columns, or result limit. If the spreadsheet has more than 100 tabs, choose another spreadsheet or reduce its tab count.

### `google_unavailable`

Google Sheets, the network, the quota store, or response validation failed temporarily or returned an unknown reason. Retry reads after a short delay; do not repeat an uncertain append.

### `google_append_target_mismatch`

Google reported a write outside the expected tab or column interval. Do not retry. Open Activity and reconcile the operation against the Sheet.

### `append_outcome_unknown`

The append request may have succeeded but its response was not trustworthy. Do not retry. Use the operation reference and UTC time in Activity to inspect the Sheet once; escalate if a human cannot establish the outcome.