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 for every stable code, Activity for the safe event view, and Support for approved contact paths.