# Troubleshoot Google Sheets Tools

Start with the safe error code, UTC time, action, and Activity status. Never paste a Google authorization code, OAuth state, token, account or file identifier, spreadsheet query, range, cell value, request body, or raw provider response into a ticket, log, prompt, or chat.

## Connection or file unavailable

Ask a workspace owner or admin to open **Settings → Integrations → Google Sheets**. A **Reconnect required** connection must reconnect with the same Google account. Use **Add spreadsheet** when the connection is healthy but the file grant is missing. V1 accepts My Drive files only; select a My Drive file when `google_shared_drive_unsupported` appears.

Revoke destroys Operade's stored access and refresh token ciphertext and makes dependent Tools unavailable. Revoke does not delete the Tools, immutable Agent versions, or past conversation history. Reconnect the same account to recover the connection; replacing it with a different Google identity is not supported in V1.

## Headers, ranges, and locked Tools

`google_sheet_reconfigure_required` means the saved tab, range, or header snapshot no longer matches the spreadsheet. Do not edit a published Tool in place. Select **Clone to change**, review the fixed target and column mapping, validate and save, run Agent Test, attach the clone to the draft, and publish a new Agent version.

`google_tool_locked` confirms that the existing Google Sheets Tool was captured by a published version. The lock protects the live capability from being redirected silently. Webhook Tools have a different lifecycle and remain mutable shared resources.

## Quota, size, and temporary failures

For `google_quota_exceeded`, wait for the bounded `retry_after_seconds` interval and make one controlled retry. Do not create parallel retries. For `google_response_too_large`, narrow the fixed range, columns, or maximum rows. Metadata also stops when a spreadsheet has more than 100 tabs; choose a smaller spreadsheet or reduce its tab count before trying again. For `google_unavailable`, retry a read after a short delay; repeated failures need operator review.

Search rows can retry selected temporary failures within its runtime limit. Add one row is stricter because a lost response can hide a successful write. Never treat a generic timeout or 5xx after an append as proof that no row was added.

## Reconcile an uncertain append

`append_outcome_unknown` means Google may have accepted the row but Operade did not receive a trustworthy final response. Do not retry the append. Open the linked Conversation **Activity** entry and record its operation reference, UTC time, Tool name, spreadsheet display name, tab, and status. Inspect the Sheet once for the intended synthetic or business row.

If the row exists, continue without another append. If it clearly does not exist, a human may decide whether a new action is safe. If the result cannot be established, escalate with the safe fields and leave the outcome unknown. `google_append_target_mismatch` uses the same no-retry reconciliation because Google reported a write outside the expected tab or column interval.

## Escalate safely

Include only the error code, `read` or `append`, UTC time, safe HTTP status class, latency bucket, bounded retry interval, truncation flag, and the Activity fields listed above for append reconciliation. Do not include internal workspace, user, connection, grant, spreadsheet, or file IDs.

See the [Google Sheets error reference](/docs/reference/google-sheets-errors) for every stable code, [Activity](/docs/monitor/transcript-and-activity) for the safe event view, and [Support](/docs/reference/support) for approved contact paths.