AI가 짠 코드가 아무 설명 없이 죽는 순간들
영상 다운로드가 안 되고, Claude 응답을 못 읽고, JSON이 중간에 끊겼다. 세 번 다 "내 코드가 잘못됐나" 싶었지만, 실제로는 외부 서비스가 돌려주는 응답 모양이 생각과 달랐던 것이었다. 에러 메시지만 보고 넘겨짚지 않는 법을 정리했다.
블로그 자동화 파이프라인을 만드는 동안, 비슷한 패턴의 에러를 세 번 겪었습니다. 셋 다 “코드에 문법 오류가 있나?” 싶게 생긴 에러였는데, 원인은 전부 제가 가정한 것과 실제 외부 서비스의 응답이 달랐다는 것이었습니다. 세 가지를 묶어서 정리합니다.
1. “요청한 포맷을 쓸 수 없습니다” — 유튜브 다운로드
영상을 내려받는 코드는 yt-dlp라는 도구를 썼습니다. 처음 짠 설정은 이랬습니다.
ydl_opts = {
"format": "best[ext=mp4]/best",
...
}
“가장 좋은 mp4 하나”를 받겠다는 뜻인데, 실행하니 이런 에러가 났습니다.
ERROR: Requested format is not available. Use --list-formats for a list of available formats
최근 유튜브는 화질이 높은 영상일수록 영상과 음성을 아예 다른 파일로 따로 제공합니다. 하나로 합쳐진 mp4 포맷만 고르게 한 제 설정으로는, 조건에 맞는 파일이 아예 없어서 실패한 것이었습니다.
고친 설정은 이렇습니다.
ydl_opts = {
"format": "bestvideo+bestaudio/best",
"merge_output_format": "mp4",
...
}
영상과 음성을 따로 받은 다음 ffmpeg로 합쳐서 mp4로 만들라는 뜻입니다. PC에 ffmpeg가 이미 설치돼 있어서 바로 됐습니다.
2. “Cannot read properties of undefined” — Claude 응답 읽기
Claude API를 호출하고 응답에서 글 내용을 꺼내는 코드는 이렇게 짰습니다.
const data = JSON.parse(res.getContentText());
const text = data.content[0].text; // 응답의 첫 번째 블록이 글 내용이라고 가정
실행하니 이런 에러가 났습니다.
TypeError: Cannot read properties of undefined (reading 'trim')
처음엔 data.content가 비어 있나 싶어 의심했습니다. 그런데 실제로는 data.content[0]이 “생각(thinking)“을 담은 블록이었고, 제가 원하는 실제 글 내용은 그다음 블록에 들어 있었습니다. 저는 “첫 번째 블록이 곧 내용”이라고 넘겨짚었는데, 실제 응답은 여러 블록으로 올 수 있었던 겁니다.
고친 코드는 “첫 번째”가 아니라 “타입이 text인 것”을 찾도록 바꿨습니다.
const textBlock = (data.content || []).find((block) => block.type === 'text');
if (!textBlock) {
throw new Error('텍스트 블록을 찾을 수 없습니다: ' + res.getContentText());
}
3. “Unterminated string in JSON” — 응답이 중간에 끊김
두 번째 문제를 고치고 나니, 이번엔 다른 에러가 났습니다.
SyntaxError: Unterminated string in JSON at position 1847
JSON 문자열이 닫히는 괄호 없이 중간에 뚝 끊겨 있다는 뜻입니다. 원인은 응답 길이 제한이었습니다. Claude API를 호출할 때 max_tokens: 4000으로 걸어 뒀는데, 글 하나를 HTML로 다 쓰기엔 이 한도가 부족해서 응답이 중간에 잘렸던 겁니다. 한도를 8000으로 올리니 끝까지 받아졌습니다.
세 가지의 공통점
다시 보니 셋 다 같은 모양의 실수였습니다.
- 외부 서비스가 항상 내가 예상한 모양으로 응답할 거라고 가정했다
- 실제로는 유튜브의 제공 포맷이 바뀌어 있었고, Claude 응답엔 여러 블록이 섞여 있었고, 응답 길이엔 한도가 있었다
- 에러 메시지만 보면 “내 코드가 틀렸다”처럼 보이지만, 사실은 가정이 틀렸다
돌아보며
이후로는 외부 API를 처음 연결할 때, 바로 본 기능을 짜지 않고 일단 받은 응답을 그대로 로그로 찍어서 눈으로 한 번 보는 단계를 꼭 넣습니다. 한 줄이면 됩니다.
Logger.log(res.getContentText());
이 한 줄을 처음부터 넣어 뒀다면, 두 번째 문제는 애초에 겪지 않았을 겁니다. 코드가 “틀렸다”가 아니라 “내가 모르는 모양으로 데이터가 온다”일 때, 제일 빠른 해결책은 더 똑똑한 코드를 짜는 게 아니라 실제 데이터를 한 번 보는 것이었습니다.