What this specific message actually means
The `!ref` property is an internal reference key used by spreadsheet-parsing libraries to describe the used-range of a worksheet. When n8n's Google Sheets node receives a worksheet object that is empty, missing, or otherwise malformed at the API level, the code that expects that key to exist throws this JavaScript error instead of a clean, human-readable message — which is why it looks cryptic compared to the node's usual error formatting.
This has been reported specifically during workflow activation for Row Updated-type triggers, which fits the pattern: activation attempts to read the current worksheet reference to establish a baseline before polling begins, and fails immediately if that reference cannot be constructed.
Check these worksheet-level conditions
- Worksheet (tab) selected in the node no longer exists or was renamed: re-open the node and re-select the sheet/tab from the dropdown rather than trusting a previously saved reference, which can point at a tab that was deleted or renamed since the node was configured.
- Selected range or sheet has genuinely zero data: a completely empty sheet (no headers, no rows) can fail to produce a valid used-range reference for some API responses — add at least a header row before activating a trigger against it.
- Spreadsheet ID itself is stale, pointing at a sheet that was deleted, moved to trash, or had its sharing permissions changed since the node was last configured.
- Merged cells or a protected range covering the configured range: less common but reported in adjacent contexts — a heavily merged or protected header area can produce an unusual API response shape for the used range, worth ruling out if the sheet has unusual formatting near row 1.
Fix by re-establishing the reference cleanly
Re-select both the spreadsheet and the specific worksheet tab from their respective dropdowns in the node (do not just leave a previously typed or pasted ID), confirm the sheet has at least a header row of real data, and save before reactivating the workflow.
If the sheet has merged cells or protected ranges near the top rows, consider unmerging the header row or moving the trigger's range to start one row below any unusual formatting, as a targeted test to rule that out.
If the error persists after confirming the worksheet is valid, non-empty, and free of unusual formatting near the used range, check whether your installed n8n version has a known related bug — this has been reported in specific version ranges and can be resolved by upgrading past the affected release.
Sources checked for this guide
Community reports describing this exact error string on activation are limited but consistent in pointing at worksheet-reference issues rather than credential or permission problems.
Frequently asked questions
Is this a permissions error in disguise?
No. It is an internal parsing error thrown when the worksheet reference cannot be read, typically because the selected tab is missing, renamed, or the sheet has no real data — not because access was denied.
Will adding a header row to an empty sheet actually fix this?
In cases where the sheet had genuinely zero data, yes — a valid used-range needs at least some content. If the sheet already has data, look at whether the selected tab itself is stale instead.
Could merged cells in my header row cause this?
It has been reported in adjacent contexts as a contributing factor for unusual used-range responses. If the sheet has merged or protected cells near the top, test unmerging them or moving the range down a row.
I re-selected the sheet and tab and it still fails — what next?
Check your n8n version against known issues for this error string; it has been reported in specific version ranges and may require an upgrade rather than a configuration change.
