疑难排解

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-CN "Hello"

# 设置默认值
yaku config set default-target zh-CN

无效的语言代码

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-CN "Bonjour"
yaku --mode polish --to en "fix the grammer"

网络错误 / API 无法连接

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

解法：

1. 检查你的网络连接。
2. 如果在代理后面，设置 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。

请求超时

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-CN --verbose

3. 检查输出是否被重定向：yaku --to zh-CN "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-CN

无效的配置值

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-CN: 对应 --to zh-CN
3. 使用 --glossary <路径> 明确加载
4. 确认 --no-glossary 没有被设置

还是卡住了？

提交一个 issue，附上：

• 你的 yaku 版本（yaku version）
• 你执行的命令
• 完整的错误信息
• 你的 backend 设置（yaku config get backend）