疑難排解

API key 未設定

API key required for gemini backend.

  Option 1: Set via config:
    yaku config set api-key your-api-key

  Option 2: Set environment variable:
    export YAKU_API_KEY=your-api-key

  Option 3: Use hosted service (no key needed):
    yaku config set backend hosted

使用自備 API 後端（Gemini、OpenAI、Anthropic）但未提供 API key 時會出現此錯誤。

解法： 按照錯誤訊息中的三個選項之一操作。最簡單的方式是使用託管後端，不需要 API key：

yaku config set backend hosted

或為你偏好的後端設定 API key。詳見後端了解完整設定說明。

未指定目標語言

Error: target language required. Use --to <lang> or set default:

  yaku config set default-target ja

解法： 傳入 --to 或設定預設值：

# 每次指定
yaku --to zh-TW "Hello"

# 設定預設值
yaku config set default-target zh-TW

無效的語言代碼

Error: unknown language "japanese". Did you mean "ja"?

解法： 使用 BCP 47 代碼，而非語言名稱：

# ❌ 錯誤
yaku --to japanese "Hello"

# ✅ 正確
yaku --to ja "Hello"

詳見語言了解常用代碼。

無效的模式

Error: invalid mode "xxx". Use "translate" or "polish"

解法： --mode 選項只接受 translate（預設）或 polish：

yaku --mode translate --to zh-TW "Bonjour"
yaku --mode polish --to en "fix the grammer"

網路錯誤 / API 無法連線

Error: failed to reach Gemini API. Check your network connection

解法：

1. 檢查你的網路連線。
2. 如果在 proxy 後面，設定 HTTP_PROXY/HTTPS_PROXY 環境變數。
3. 如果使用 OpenAI 相容提供者，確認 --api-base 是否正確。

輸入過長

Error: input too long (8000 chars). Hosted service limit: 5000 chars per request

當文字超過你的方案的每次請求字元上限時會出現此錯誤。上限取決於你的方案等級——詳見託管服務與方案。

解法：

• 登入 — yaku login 可將上限從 5,000（匿名）提升到 10,000（免費方案）字元。
• 將文字拆分成較小的區塊。
• 使用自備 API 後端（Gemini、OpenAI、Anthropic）搭配你自己的 API key——自備 API 後端沒有字元限制。
• 用 yaku quota 查看你目前的限制。

配額超過限制

Error: Daily limit reached (50/50). Run "yaku login" for higher limits, or use your own API key: yaku config set api-key
More info: https://docs.yakulang.com/guides/hosted-service/

你已經用完託管服務的每日或每月請求次數。

解法：

• 登入 — yaku login 可將每月上限從 100（匿名）提升到 300（免費方案）。
• 使用你自己的 API key — yaku config set api-key <key> 搭配自備 API 後端，沒有配額限制。
• 等待 — 每日限制在 UTC 午夜重置。
• 用 yaku quota 查看你目前的使用量。

詳見託管服務與方案了解完整方案說明。

找不到模型

Error: model not found or no longer available. Omit --model to use the default

當 --model 值不符合你的後端上任何可用模型時會出現此錯誤。

解法：

• 省略 --model 以使用預設模型。
• 對照你的提供者文件確認模型名稱。

超過速率限制

Error: API rate limit exceeded.

解法： 稍候再重試。如果經常發生：

• 切換到不同的後端（--backend openai）
• 使用 yaku login 登入託管後端以獲取更高配額
• 查閱你的 API 提供者的速率限制文件

無效或未授權的 API key

Error: invalid or unauthorized API key. Check your key:

  yaku config get api-key
  yaku config set api-key <new-key>

解法：

1. 確認你的 key：yaku config get api-key
2. 確認 key 與你使用的後端相符（例如 Gemini key 搭配 --backend gemini，而非 --backend openai）。
3. 從你的提供者儀表板重新產生 key。

所有後端（Gemini、OpenAI、Anthropic）都會為認證失敗提供可操作的錯誤訊息，包含檢查和更新 key 的指令。

請求逾時

Error: request timed out. The API did not respond in time. Try again later

解法： yaku 每次請求有 30 秒逾時。對於大型檔案：

• 將檔案拆分成較小的區塊
• 檢查你的網路連線速度
• 嘗試不同的後端

沒有輸出

如果 yaku 沒有產生輸出：

1. 輸入是否為空？（echo "" | yaku 不會產生輸出）
2. 使用 --verbose 確認 API 呼叫是否成功：

   echo "test" | yaku --to zh-TW --verbose

3. 檢查輸出是否被重導：yaku --to zh-TW "test" 2>/dev/null

設定檔語法錯誤

Warning: config file ~/.config/yaku/config.yaml has invalid YAML syntax: ...
  Open the file and fix the syntax, or delete it and reconfigure:
    ~/.config/yaku/config.yaml
  Using default config until fixed.

解法： yaku 會記錄警告但以預設值繼續執行。修正方式：

# 找到設定檔
yaku config path

# 手動編輯或刪除後重設
rm ~/.config/yaku/config.yaml
yaku config set default-target zh-TW

無效的設定值

Error: invalid value "abcdefg" for backend. Valid values: hosted, gemini, openai, anthropic

使用 yaku config set 時傳入無法辨識的值會出現此錯誤。

解法： 使用錯誤訊息中顯示的有效值。例如：

yaku config set backend gemini

會驗證的欄位包括 backend（必須是 hosted、gemini、openai、anthropic 其中之一）和 default-target（必須是有效的 BCP 47 語言代碼）。

YAKU_API_KEY 已設定但為空

Error: YAKU_API_KEY is set but empty (check your key source).

  Example: YAKU_API_KEY=$(cat /path/to/key) yaku --backend gemini ...

當 YAKU_API_KEY 被設為空字串時會出現此錯誤——通常是因為提供 key 的指令靜默失敗了（例如 $(vault read ...) 沒有回傳任何內容）。

解法： 檢查提供 key 的指令或檔案。如果你不打算設定 YAKU_API_KEY，請取消設定：

unset YAKU_API_KEY

工作階段已過期或無效

Session expired or invalid. Run yaku login to re-authenticate.

執行 yaku whoami 時，若儲存的工作階段已失效會出現此錯誤。CLI 會自動重新整理工作階段，但如果工作階段已完全過期，你需要重新認證。

解法： 重新認證：

yaku login

術語表未載入

如果術語表的詞彙未被套用：

1. 檢查檔案是否存在：ls .yaku-glossary.yaml
2. 確認語言區段與你的 --to 目標相符（不區分大小寫）：zh-TW: 對應 --to zh-TW
3. 使用 --glossary <路徑> 明確載入
4. 確認 --no-glossary 沒有被設定

還是卡住了？

開一個 issue，附上：

• 你的 yaku 版本（yaku version）
• 你執行的指令
• 完整的錯誤訊息
• 你的 backend 設定（yaku config get backend）