비개발자 연구실

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으로 올리니 끝까지 받아졌습니다.

세 가지의 공통점

다시 보니 셋 다 같은 모양의 실수였습니다.

  1. 외부 서비스가 항상 내가 예상한 모양으로 응답할 거라고 가정했다
  2. 실제로는 유튜브의 제공 포맷이 바뀌어 있었고, Claude 응답엔 여러 블록이 섞여 있었고, 응답 길이엔 한도가 있었다
  3. 에러 메시지만 보면 “내 코드가 틀렸다”처럼 보이지만, 사실은 가정이 틀렸다

돌아보며

이후로는 외부 API를 처음 연결할 때, 바로 본 기능을 짜지 않고 일단 받은 응답을 그대로 로그로 찍어서 눈으로 한 번 보는 단계를 꼭 넣습니다. 한 줄이면 됩니다.

Logger.log(res.getContentText());

이 한 줄을 처음부터 넣어 뒀다면, 두 번째 문제는 애초에 겪지 않았을 겁니다. 코드가 “틀렸다”가 아니라 “내가 모르는 모양으로 데이터가 온다”일 때, 제일 빠른 해결책은 더 똑똑한 코드를 짜는 게 아니라 실제 데이터를 한 번 보는 것이었습니다.

← 연구 기록 목록