Troubleshooting

API key required

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

This error appears when using a local backend (Gemini, OpenAI, Anthropic) without an API key.

Fix: Follow one of the three options shown in the error message. The simplest path is to use the hosted backend, which needs no API key:

yaku config set backend hosted

Or set an API key for your preferred backend. See Backends for full setup instructions.

No target language specified

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

  yaku config set default-target ja

Fix: Pass --to or set a default:

# Per command
yaku --to en "Bonjour"

# Set a default
yaku config set default-target en

Invalid language code

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

Fix: Use a BCP 47 code, not the language name:

# ❌ Wrong
yaku --to japanese "Hello"

# ✅ Correct
yaku --to ja "Hello"

See Languages for common codes.

Invalid mode

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

Fix: The --mode flag only accepts translate (default) or polish:

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

Network error / API unreachable

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

Fix:

1. Check your internet connection.
2. If behind a proxy, set HTTP_PROXY/HTTPS_PROXY environment variables.
3. If using an OpenAI-compatible provider, verify --api-base is correct.

Input too long

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

This error appears when your text exceeds the per-request character limit for your plan. The limit depends on your plan tier — see Hosted Service & Plans for details.

Fix:

• Log in — yaku login raises the limit from 5,000 (anonymous) to 10,000 (free) characters.
• Split the text into smaller chunks.
• Use a local backend (Gemini, OpenAI, Anthropic) with your own API key — local backends have no character limit.
• Check your current limits with yaku quota.

Model not found

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

This error appears when the --model value does not match any model available on your backend.

Fix:

• Omit --model to use the default model.
• Check the model name against your provider’s documentation.

Rate limit exceeded

Error: API rate limit exceeded.

Fix: Wait and retry. If this happens frequently:

• Switch to a different backend (--backend openai)
• Use the hosted backend with yaku login for higher quotas
• Check your API provider’s rate limit documentation

Invalid or unauthorized API key

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

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

Fix:

1. Verify your key: yaku config get api-key
2. Check that the key matches the backend you’re using (e.g., a Gemini key with --backend gemini, not --backend openai).
3. Regenerate the key from your provider’s dashboard.

Request timed out

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

Fix: yaku has a 30-second timeout per request. For large files:

• Split the file into smaller chunks
• Check your internet connection speed
• Try a different backend

Empty output

If yaku produces no output:

1. Is the input empty? (echo "" | yaku returns nothing)
2. Check --verbose to verify the API call succeeded:

   echo "test" | yaku --to en --verbose

3. Check if output is being redirected: yaku --to en "test" 2>/dev/null

Config file syntax error

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.

Fix: yaku logs a warning but continues with defaults. To fix:

# Find the config file
yaku config path

# Edit it manually or reset by deleting it
rm ~/.config/yaku/config.yaml
yaku config set default-target en

Invalid config value

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

This error appears when running yaku config set with an unrecognized value.

Fix: Use one of the valid values shown in the error message. For example:

yaku config set backend gemini

Validated fields include backend (must be one of hosted, gemini, openai, anthropic) and default-target (must be a valid BCP 47 language code).

YAKU_API_KEY is set but empty

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

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

This error appears when YAKU_API_KEY is set to an empty string — typically because a key-sourcing command failed silently (e.g., $(vault read ...) returned nothing).

Fix: Check the command or file that provides your key. If you don’t intend to set YAKU_API_KEY, unset it:

unset YAKU_API_KEY

Session expired or invalid

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

This error appears when running yaku whoami and the stored session is no longer valid. The CLI refreshes sessions automatically, but if the session has fully expired, you need to re-authenticate.

Fix: Re-authenticate:

yaku login

Glossary not loading

If glossary terms are not being applied:

1. Check the file exists: ls .yaku-glossary.yaml
2. Check the language section matches your --to target (case-insensitive): en: for --to en
3. Use --glossary <path> for explicit loading
4. Make sure --no-glossary is not set

Still stuck?

Open an issue with:

• Your yaku version (yaku version)
• The command you ran
• The full error message
• Your backend setting (yaku config get backend)