문제 해결

API 키 필요

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

로컬 백엔드(Gemini, OpenAI, Anthropic)를 API 키 없이 사용할 때 이 오류가 나타납니다.

해결: 오류 메시지에 표시된 세 가지 옵션 중 하나를 따르세요. 가장 간단한 방법은 API 키가 필요 없는 호스팅 백엔드를 사용하는 것입니다:

yaku config set backend hosted

또는 선호하는 백엔드의 API 키를 설정하세요. 전체 설정 방법은 백엔드를 참조하세요.

대상 언어 미지정

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

  yaku config set default-target ko

해결: --to를 전달하거나 기본값을 설정합니다:

# 명령별
yaku --to ko "Hello"

# 기본값 설정
yaku config set default-target ko

유효하지 않은 언어 코드

Error: unknown language "korean". Did you mean "ko"?

해결: 언어 이름이 아닌 BCP 47 코드를 사용하세요:

# 잘못됨
yaku --to korean "Hello"

# 올바름
yaku --to ko "Hello"

일반적인 코드는 언어를 참조하세요.

유효하지 않은 모드

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

해결: --mode 옵션은 translate(기본값) 또는 polish만 허용합니다:

yaku --mode translate --to ko "Hello"
yaku --mode polish --to en "fix the grammer"

네트워크 오류 / API 접근 불가

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

해결:

인터넷 연결을 확인하세요.
프록시 뒤에 있다면 HTTP_PROXY/HTTPS_PROXY 환경 변수를 설정하세요.
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)를 사용합니다. 로컬 백엔드에는 글자 수 제한이 없습니다.
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 키 사용 — 로컬 백엔드에서 yaku config set api-key <key>를 설정하면 할당량 제한이 없습니다.
대기 — 일일 한도는 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 키

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

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

해결:

키를 확인합니다: yaku config get api-key
키가 사용 중인 백엔드와 일치하는지 확인합니다(예: Gemini 키를 --backend gemini에, --backend openai에 사용하지 않도록).
제공자 대시보드에서 키를 재생성합니다.

요청 시간 초과

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

해결: yaku는 요청당 30초 제한이 있습니다. 큰 파일의 경우:

파일을 작은 조각으로 나눕니다
인터넷 연결 속도를 확인합니다
다른 백엔드를 시도합니다

빈 출력

yaku가 출력을 생성하지 않는 경우:

입력이 비어 있나요? (echo "" | yaku는 아무것도 반환하지 않습니다)
--verbose로 API 호출 성공 여부를 확인하세요:
Terminal window
```
echo "test" | yaku --to ko --verbose
```
출력이 리다이렉트되는지 확인하세요: yaku --to ko "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 ko

유효하지 않은 설정 값

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가 빈 문자열로 설정된 경우 이 오류가 나타납니다. 일반적으로 키 소싱 명령이 조용히 실패한 경우입니다(예: $(vault read ...)가 아무것도 반환하지 않음).

해결: 키를 제공하는 명령이나 파일을 확인하세요. YAKU_API_KEY를 설정하지 않으려면 해제하세요:

unset YAKU_API_KEY

세션 만료 또는 유효하지 않음

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

yaku whoami를 실행할 때 저장된 세션이 더 이상 유효하지 않으면 이 오류가 나타납니다. CLI는 세션을 자동으로 갱신하지만, 세션이 완전히 만료되면 재인증이 필요합니다.

해결: 재인증하세요:

yaku login

용어집이 로드되지 않음

용어집 용어가 적용되지 않는 경우:

파일이 존재하는지 확인하세요: ls .yaku-glossary.yaml
언어 섹션이 --to 대상과 일치하는지 확인하세요(대소문자 무관): --to ko에는 ko:
명시적 로드에 --glossary <경로>를 사용하세요
--no-glossary가 설정되지 않았는지 확인하세요

여전히 해결되지 않나요?

다음 정보를 포함하여 이슈를 열어 주세요:

yaku 버전 (yaku version)
실행한 명령
전체 오류 메시지
backend 설정 (yaku config get backend)