Troubleshooting

uv: command not found

Cause: uv was just installed, but the open terminal still has the old PATH.

Fix: close and reopen the terminal (or run source ~/.local/bin/env on macOS/Linux). Check with uv --version. uv lives in ~/.local/bin (macOS/Linux) or %USERPROFILE%\.local\bin (Windows).

macOS: “install.command can't be opened because it is from an unidentified developer”

Cause: Gatekeeper — the script isn't signed with an Apple Developer certificate.

Fix: right-click the file → Open → confirm. Or run bash install.command in Terminal from inside the folder.

macOS: “could not be executed because you do not have appropriate access privileges”

Cause: the unzip tool dropped the file's execute permission.

Fix: in Terminal, inside the folder, run bash install.command — or restore the bit once with chmod +x install.command.

Windows: “running scripts is disabled on this system”

Cause: PowerShell's execution policy blocks unsigned scripts.

Fix: open PowerShell in the folder and run powershell -ExecutionPolicy Bypass -File install.ps1. This applies to that one run only and leaves your system policy unchanged.

The installer stops at “Smoke-testing InnerSheet”

Cause: on the first run uv downloads Python and the dependencies. No internet, a proxy, or a firewall stops it.

Fix: run uv run server.py --version yourself to see the real error. Behind a corporate proxy, set HTTPS_PROXY first. Then run the installer again — it is safe to repeat.

Error 403: access_denied — “has not completed the Google verification process”

Cause: your OAuth app is in Testing and the account you signed in with is not a test user.

Fix: in Google Cloud, open Google Auth Platform → Audience (older: OAuth consent screen) and either click Publish app (recommended), or add your Gmail under Test users. Then try again. Details on the Install page.

“Google hasn't verified this app”

Cause: expected for a project you created yourself — it is your own app, not a third party.

Fix: click Advanced → Go to InnerSheet (unsafe). Personal projects never need Google's verification; the security page explains when it would matter.

invalid_grant — “Token has been expired or revoked”

Cause: while the OAuth app is in Testing, Google expires the sign-in after 7 days. Revoking access in your Google account does the same.

Fix: delete ~/.config/innersheet/token.json (or your SHEETS_MCP_TOKEN_PATH) and restart the client to sign in again. To stop it recurring, Publish app under Google Auth Platform → Audience.

Error 400: redirect_uri_mismatch

Cause: the OAuth client was created as Web application. InnerSheet signs in through a local loopback address, which only a Desktop app client allows.

Fix: create a new client of type Desktop app, download its JSON, and replace client_secret.json.

“Google Sheets API has not been used in project … before or it is disabled”

Cause: the API isn't enabled in the Cloud project that owns your OAuth client. The same message can mention the Drive API.

Fix: open the link in the error (or APIs & Services → Library), enable Google Sheets API and Google Drive API, wait a minute, and try again.

“OAuth mode needs GOOGLE_OAUTH_CLIENT_SECRETS pointing at your Google Cloud OAuth client JSON”

Cause: the server can't find client_secret.json at the path in your config — usually the file was never saved, has a different name (client_secret_1234….json), or the folder moved.

Fix: rename the downloaded file to client_secret.json, put it in the innersheet folder, and check that GOOGLE_OAUTH_CLIENT_SECRETS in your client config points at it. Restart the client.

The Google sign-in page never opens, or sign-in loops

Cause: no desktop browser (SSH session, server, container), or a broken cached token. A wrong system clock also breaks OAuth.

Fix: sign in once on a machine with a browser, then copy ~/.config/innersheet/token.json to the same path on the server. For a loop, delete token.json and check the clock. For servers, a service account avoids browser sign-in entirely.

Claude Desktop doesn't show InnerSheet

Cause: the app wasn't fully restarted, or the config was written somewhere else.

Fix:

1. Quit fully — ⌘Q on macOS, tray icon → Quit on Windows — and reopen.
2. Open Settings → Developer → Edit Config and check the innersheet entry is there.
3. Read mcp-server-innersheet.log in the Claude logs folder for the real error.

spawn uv ENOENT (or “command not found: uv” in the client log)

Cause: desktop apps opened from the Dock or Start menu don't always see the PATH your terminal uses, so the bare command "uv" isn't found.

Fix: put the full path in the config. Run which uv (macOS/Linux) or where uv (Windows) and use the result:

"command": "/Users/yourname/.local/bin/uv"

The client says its config file is not valid JSON

Cause: a hand edit left a trailing comma or missing quote — or, on Windows PowerShell 5.1, the file was saved with a byte-order mark (BOM) that some apps reject.

Fix: restore the backup the installer made (claude_desktop_config.json.bak-… next to the config), or paste the file into a JSON validator and fix the reported line. For a BOM, open the file in Notepad and Save as → Encoding: UTF-8.

“Server disconnected” / the server keeps restarting

Cause: the server process exits on start — a wrong path, a missing file, or a Python error.

Fix: copy the command and args from your config and run them in a terminal. The error you see there is the real cause; look it up on this page.

ChatGPT or Claude.ai can't connect

Cause: web chats only reach remote servers over HTTPS — a local install isn't reachable.

Fix: deploy with --transport http behind HTTPS and add the URL as a custom connector (steps). Two errors to know:

• ERROR: HTTP transport requires SHEETS_MCP_API_KEY — set the key before starting; the server refuses to run without one.
• 401 Unauthorized: a valid Bearer API key is required — the client isn't sending Authorization: Bearer <key>, or the key differs.

“Range is not valid” / unknown sheet name

Cause: the tab name in the range doesn't exist, or contains spaces without quotes.

Fix: the error lists the real sheet names — use one exactly, quoted if it has spaces: 'My Sheet'!A1:D10.

“Invalid spreadsheet id”

Cause: the agent passed a name or a full URL instead of the ID.

Fix: use the part of the URL between /d/ and /edit, or ask the agent to find the sheet by name first.

“Spreadsheet is not in the allowlist (SHEETS_MCP_ALLOWED_SPREADSHEETS)”

Cause: an allowlist is set and this spreadsheet isn't on it.

Fix: add its ID to SHEETS_MCP_ALLOWED_SPREADSHEETS (comma-separated) or remove the variable, then restart the client.

“SHEETS_MCP_READ_ONLY is on: writes are disabled.”

Cause: read-only mode is on — working as intended.

Fix: to allow writes, remove SHEETS_MCP_READ_ONLY, delete token.json once (the old token only has read permission), and restart.

“Refusing to write N cells in one call”

Cause: one write exceeds SHEETS_MCP_MAX_WRITE_CELLS (default 10,000).

Fix: ask the agent to split the write into batches, or raise the limit if you are sure.

“Truncated: sheet has ~N cells in range, showing the first 5000”

Cause: a read exceeded SHEETS_MCP_MAX_READ_CELLS (default 5,000) — this protects the agent's context window.

Fix: ask for a narrower range, or raise the limit.

403: The caller does not have permission

Cause: the signed-in account — or the service account — can't open this spreadsheet.

Fix: share the sheet with that account (for a service account, its …@….iam.gserviceaccount.com email) as Editor, or sign in with the account that owns it.

HTTP 429 — quota exceeded

Cause: Google allows 300 reads and 300 writes per minute per project, 60 of each per user.

Fix: wait a minute, and ask the agent to batch updates (batch_update_values) instead of writing cell by cell.