Xử lý lỗi

uv: command not found

Nguyên nhân: uv vừa được cài, nhưng terminal đang mở vẫn dùng PATH cũ.

Cách sửa: đóng và mở lại terminal (hoặc chạy source ~/.local/bin/env trên macOS/Linux). Kiểm tra bằng uv --version. uv nằm ở ~/.local/bin (macOS/Linux) hoặc %USERPROFILE%\.local\bin (Windows).

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

Nguyên nhân: Gatekeeper — script chưa được ký bằng chứng chỉ Apple Developer.

Cách sửa: nhấp chuột phải vào file → Open → xác nhận. Hoặc mở Terminal trong thư mục và chạy bash install.command.

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

Nguyên nhân: công cụ giải nén làm mất quyền thực thi của file.

Cách sửa: mở Terminal trong thư mục và chạy bash install.command — hoặc trả lại quyền một lần bằng chmod +x install.command.

Windows: “running scripts is disabled on this system”

Nguyên nhân: execution policy của PowerShell chặn script chưa ký.

Cách sửa: mở PowerShell trong thư mục và chạy powershell -ExecutionPolicy Bypass -File install.ps1. Lệnh này chỉ áp dụng cho lần chạy đó, không đổi chính sách của máy.

Trình cài dừng ở bước “Smoke-testing InnerSheet”

Nguyên nhân: lần đầu uv phải tải Python và các thư viện về. Không có internet, đi qua proxy hoặc bị firewall chặn sẽ làm bước này lỗi.

Cách sửa: tự chạy uv run server.py --version để thấy lỗi thật. Nếu mạng công ty dùng proxy, đặt HTTPS_PROXY trước. Rồi chạy lại trình cài — chạy lại nhiều lần vẫn an toàn.

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

Nguyên nhân: ứng dụng OAuth đang ở trạng thái Testing và tài khoản bạn đăng nhập chưa có trong danh sách test user.

Cách sửa: trong Google Cloud, mở Google Auth Platform → Audience (bản cũ: OAuth consent screen) rồi hoặc nhấn Publish app (nên dùng), hoặc thêm Gmail của bạn vào Test users. Sau đó thử lại. Chi tiết ở trang Cài đặt.

“Google hasn't verified this app”

Nguyên nhân: bình thường với project bạn tự tạo — đó là ứng dụng của chính bạn, không phải bên thứ ba.

Cách sửa: nhấn Advanced → Go to InnerSheet (unsafe). Project cá nhân không bao giờ cần Google xác minh; trang bảo mật giải thích khi nào việc đó mới quan trọng.

invalid_grant — “Token has been expired or revoked”

Nguyên nhân: khi ứng dụng OAuth còn ở Testing, Google làm hết hạn đăng nhập sau 7 ngày. Thu hồi quyền trong tài khoản Google cũng gây ra lỗi này.

Cách sửa: xóa ~/.config/innersheet/token.json (hoặc file ở SHEETS_MCP_TOKEN_PATH) rồi khởi động lại client để đăng nhập lại. Để lỗi không lặp lại, nhấn Publish app ở Google Auth Platform → Audience.

Error 400: redirect_uri_mismatch

Nguyên nhân: OAuth client được tạo với loại Web application. InnerSheet đăng nhập qua một địa chỉ loopback trên máy, và chỉ client loại Desktop app cho phép điều đó.

Cách sửa: tạo client mới loại Desktop app, tải JSON về và thay cho client_secret.json.

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

Nguyên nhân: API chưa được bật trong Cloud project chứa OAuth client của bạn. Thông báo tương tự có thể nhắc tới Drive API.

Cách sửa: mở link trong thông báo lỗi (hoặc APIs & Services → Library), bật Google Sheets API và Google Drive API, đợi khoảng một phút rồi thử lại.

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

Nguyên nhân: server không tìm thấy client_secret.json ở đường dẫn trong cấu hình — thường do chưa lưu file, file mang tên khác (client_secret_1234….json), hoặc thư mục đã bị di chuyển.

Cách sửa: đổi tên file tải về thành client_secret.json, đặt trong thư mục innersheet, và kiểm tra GOOGLE_OAUTH_CLIENT_SECRETS trong cấu hình client trỏ đúng tới nó. Khởi động lại client.

Trang đăng nhập Google không mở, hoặc đăng nhập lặp vòng

Nguyên nhân: máy không có trình duyệt (SSH, server, container), hoặc token đã lưu bị hỏng. Đồng hồ hệ thống sai cũng làm hỏng OAuth.

Cách sửa: đăng nhập một lần trên máy có trình duyệt, rồi chép ~/.config/innersheet/token.json sang cùng đường dẫn trên server. Nếu lặp vòng, xóa token.json và kiểm tra đồng hồ. Với server, dùng service account để khỏi phải đăng nhập qua trình duyệt.

Claude Desktop không hiện InnerSheet

Nguyên nhân: app chưa được khởi động lại hẳn, hoặc cấu hình bị ghi vào chỗ khác.

Cách sửa:

1. Thoát hẳn — ⌘Q trên macOS, biểu tượng khay → Quit trên Windows — rồi mở lại.
2. Mở Settings → Developer → Edit Config và kiểm tra có mục innersheet.
3. Đọc mcp-server-innersheet.log trong thư mục log của Claude để thấy lỗi thật.

spawn uv ENOENT (hoặc “command not found: uv” trong log của client)

Nguyên nhân: app desktop mở từ Dock hay menu Start không phải lúc nào cũng thấy PATH mà terminal dùng, nên lệnh trần "uv" không được tìm thấy.

Cách sửa: ghi đường dẫn đầy đủ vào cấu hình. Chạy which uv (macOS/Linux) hoặc where uv (Windows) rồi dùng kết quả:

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

Client báo file cấu hình không phải JSON hợp lệ

Nguyên nhân: sửa tay để sót dấu phẩy cuối hay thiếu dấu nháy — hoặc trên Windows PowerShell 5.1, file được lưu kèm BOM (byte-order mark) mà một số app không chấp nhận.

Cách sửa: khôi phục bản sao lưu trình cài đặt đã tạo (claude_desktop_config.json.bak-… nằm cạnh file cấu hình), hoặc dán file vào một công cụ kiểm tra JSON và sửa dòng bị báo. Với BOM, mở file bằng Notepad và chọn Save as → Encoding: UTF-8.

“Server disconnected” / server liên tục khởi động lại

Nguyên nhân: process server thoát ngay khi khởi động — sai đường dẫn, thiếu file, hoặc lỗi Python.

Cách sửa: chép command và args trong cấu hình rồi chạy trong terminal. Lỗi hiện ra ở đó là nguyên nhân thật; tra nó trên trang này.

ChatGPT hoặc Claude.ai không kết nối được

Nguyên nhân: web chat chỉ tới được server remote qua HTTPS — bản cài local không với tới được.

Cách sửa: triển khai với --transport http sau HTTPS rồi thêm URL làm custom connector (các bước). Hai lỗi cần biết:

• ERROR: HTTP transport requires SHEETS_MCP_API_KEY — đặt key trước khi khởi động; server từ chối chạy nếu thiếu.
• 401 Unauthorized: a valid Bearer API key is required — client không gửi Authorization: Bearer <key>, hoặc gửi sai key.

“Range is not valid” / tên sheet không tồn tại

Nguyên nhân: tên tab trong vùng không tồn tại, hoặc có khoảng trắng mà không đặt trong dấu nháy.

Cách sửa: thông báo lỗi liệt kê các tên sheet thật — dùng đúng một tên, đặt trong dấu nháy nếu có khoảng trắng: 'My Sheet'!A1:D10.

“Invalid spreadsheet id”

Nguyên nhân: AI truyền tên hoặc nguyên URL thay vì ID.

Cách sửa: dùng phần URL nằm giữa /d/ và /edit, hoặc nhờ AI tìm sheet theo tên trước.

“Spreadsheet is not in the allowlist (SHEETS_MCP_ALLOWED_SPREADSHEETS)”

Nguyên nhân: đã đặt danh sách cho phép và bảng tính này không có trong đó.

Cách sửa: thêm ID của nó vào SHEETS_MCP_ALLOWED_SPREADSHEETS (cách nhau bằng dấu phẩy) hoặc bỏ biến này, rồi khởi động lại client.

“SHEETS_MCP_READ_ONLY is on: writes are disabled.”

Nguyên nhân: đang bật chế độ chỉ đọc — đúng như thiết kế.

Cách sửa: muốn cho ghi, bỏ SHEETS_MCP_READ_ONLY, xóa token.json một lần (token cũ chỉ có quyền đọc), rồi khởi động lại.

“Refusing to write N cells in one call”

Nguyên nhân: một lần ghi vượt SHEETS_MCP_MAX_WRITE_CELLS (mặc định 10.000).

Cách sửa: nhờ AI chia lần ghi thành nhiều batch, hoặc tăng giới hạn nếu bạn chắc chắn.

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

Nguyên nhân: lần đọc vượt SHEETS_MCP_MAX_READ_CELLS (mặc định 5.000) — giới hạn này bảo vệ ngữ cảnh của AI.

Cách sửa: yêu cầu vùng hẹp hơn, hoặc tăng giới hạn.

403: The caller does not have permission

Nguyên nhân: tài khoản đang đăng nhập — hoặc service account — không mở được bảng tính này.

Cách sửa: chia sẻ sheet cho tài khoản đó (với service account là email …@….iam.gserviceaccount.com) ở quyền Editor, hoặc đăng nhập bằng tài khoản sở hữu sheet.

HTTP 429 — vượt hạn mức

Nguyên nhân: Google cho phép 300 lần đọc và 300 lần ghi mỗi phút cho mỗi project, 60 lần mỗi loại cho mỗi người dùng.

Cách sửa: đợi một phút, và nhờ AI gộp các lần ghi (batch_update_values) thay vì ghi từng ô.