Troubleshoot
AI 에러 해결 가이드
Claude·OpenAI·Vercel·Supabase·Next.js 같은 AI 개발 스택에서 자주 만나는 에러와 단계별 해결법을 한국어로 정리했습니다.
ERROR
Claude API 401 Unauthorized 해결
Claude API 호출 시 `{"type": "error", "error": {"type": "authentication_error"}}` 응답.
해결법 보기
ERROR
ChatGPT가 한국어로 답하지 않을 때
한국어로 질문했는데 영어로 답하거나, 한자·영어 혼용 어색한 한국어로 응답.
해결법 보기
ERROR
OpenAI 429 Rate Limit 에러 해결
API 호출이 `429 Too Many Requests` 또는 `RateLimitError`로 실패.
해결법 보기
ERROR
Claude Prompt Caching 미적용 디버깅
API 응답의 `usage.cache_read_input_tokens`가 항상 0. 비용 절감 효과 없음.
해결법 보기
ERROR
Vercel Build Failed — 흔한 원인 5가지
Vercel 배포 시 `Command "npm run build" exited with 1` 또는 `Error occurred prerendering page`.
해결법 보기
ERROR
Supabase Row Level Security 차단 디버깅
쿼리는 성공(200)하지만 결과가 항상 빈 배열. 콘솔에서는 데이터 보이는데 클라이언트에서 못 받음.
해결법 보기
ERROR
Next.js Hydration Mismatch 잡기
콘솔에 `Hydration failed because the initial UI does not match what was rendered on the server` 경고와 페이지 깜빡임.
해결법 보기
ERROR
Claude Code MCP 서버 연결 안 될 때
`/mcp` 명령에서 서버가 "not connected"로 표시되거나 도구 호출 시 timeout.
해결법 보기
ERROR
Anthropic 토큰 한도 초과 (context overflow)
응답이 `prompt is too long: X tokens > Y maximum` 또는 4xx 에러로 실패.
해결법 보기
ERROR
OpenAI Streaming 응답 중단 디버깅
스트리밍이 잘 시작되다가 중간에 멈춤. 또는 일정 시간 후 connection closed.
해결법 보기