이미지를 다시 빌드했을 뿐인데 런타임이 깨졌다 초안
10월 초, 음성 전사가 metadata_errors 인자에 대한 TypeError로 죽었다. 전사 코드는 건드린 적이 없었다. 바뀐 것은 이미지를 다시 빌드했다는 사실뿐이었다.
처음 겪는 일은 아니었다. 커뮤니티용 텔레그램 봇은 파이썬으로 짜여 있고 Docker 이미지로 배포하는데, requirements.txt의 의존성이 대부분 패키지>=하한 꼴이었다. 2026년 7월부터 10월 사이에 이 방식 때문에 기능 세 개가 런타임에서 깨졌고, 고치는 커밋이 네 번 나왔다. 빌드는 매번 문제없이 통과했다.
내가 import하지 않는 패키지가 올랐다
음성 전사에는 faster-whisper를 쓰고 requirements에는 faster-whisper>=1.0으로 적혀 있었다. 설치된 것은 1.2.1이었다. faster-whisper는 오디오 디코딩에 PyAV(av 패키지)를 쓰는데, 그 안의 decode_audio가 이렇게 호출한다.
av.open(..., metadata_errors="ignore")
PyAV는 내 코드가 직접 import하지 않는 전이 의존성이라 requirements에 적혀 있지도 않았다. 이미지 재빌드 때 PyAV가 19.0.0으로 올라갔고, 19에서는 그 인자가 없어졌다. 18.1.0으로 내려서 decode_audio가 정상 동작하는 것을 확인한 뒤 상한을 걸었다.
faster-whisper>=1.0
# faster-whisper 1.2.1 은 av.open(metadata_errors=…) 를 부르는데 PyAV 19 가 그 인자를
# 없앴다 → 전사가 TypeError 로 죽는다. faster-whisper 가 따라올 때까지 묶어 둔다.
av<19
이 핀은 faster-whisper가 PyAV 19에 맞춰 바뀌면 풀어야 한다. 그래서 왜 묶었고 언제 풀 수 있는지를 주석으로 같이 남겼다.
설치는 네 번 다 성공했다
네 건 모두 pip install은 성공했다. 버전 범위가 서로 충돌하지 않았기 때문이다. 파이썬에서는 없는 메서드를 부르거나 없는 인자를 넘기는 것이 그 줄이 실행될 때에야 오류가 된다. 설치가 성공하고 봇이 기동해도 해당 기능을 누군가 실제로 쓰기 전까지는 고장이 드러나지 않는다. 그래서 발견한 시점에는 “그 코드는 안 바꿨는데 깨졌다”로 보인다.
7월 말, 하한을 올리고 몇 분 뒤에 5.0.1이 깔렸다
석 달 전에는 문서 파일을 만들어 주는 기능이 AttributeError로 죽었다. 이것도 그 기능의 코드를 건드리지 않았는데 일어났다.
문서 생성에는 HWPX 파일을 다루는 python-hwpx를 쓰고, requirements에는 python-hwpx>=3.5로 적혀 있었다. 이미지를 재빌드하자 4.x가 설치됐는데, 4.x는 문서 객체의 save()를 없애고 to_bytes()와 save_to_stream()으로 나눴다. 코드는 여전히 save()를 부르고 있었다.
코드 쪽 수정은 간단했다.
- buf = BytesIO()
- doc.save(buf)
- return buf.getvalue()
+ return doc.to_bytes()
3.x가 깔린 환경에서 새 코드가 거꾸로 죽지 않도록 하한도 >=4.2로 올렸다.
그러고 이미지를 다시 빌드했더니 이번에는 5.0.1이 설치됐다. 하한을 올린 커밋에서 몇 분 뒤의 일이다. >=4.2는 “4.2 이상이면 무엇이든”이라는 뜻이니 당연한 결과였다. 방금 4.x에서 당한 일을 5.x에서 그대로 당할 수 있었다.
운이 좋아서 5.x에서도 동작했다. 다만 그것을 가정하지 않고 실제로 문서를 한 장 만들어 확인한 다음 상한을 걸었다.
-python-hwpx>=4.2
+python-hwpx>=5.0,<6
requirements의 주석에도 절차를 적었다. 메이저가 오르면 실제로 문서를 한 장 만들어 보고 나서 상한을 올린다. 상한을 걸어 두면 버전이 오르는 시점을 재빌드가 아니라 내가 정한다.
7월 초 것은 오류조차 없었다
가장 먼저 고친 건 성격이 좀 다르다. 버전이 올라간 문제가 아니고 처음부터 빠져 있던 의존성이었다.
사진 여러 장이 한 묶음으로 올라오는 앨범을 처리할 때, 묶음이 다 도착하기를 3초 기다리는 타이머가 한 번도 돌지 않았다. 타이머를 걸 수 없으면 즉시 발송으로 넘어가게 짜 두었기 때문에 매번 그 폴백을 탔고, 사진이 누락될 수 있는 상태였다. 오류는 없었다.
python-telegram-bot(PTB)의 JobQueue는 APScheduler가 있어야 동작하고, 그 패키지는 job-queue라는 optional extra로 설치된다. extra 없이 설치하면 app.job_queue는 None이 된다.
JobQueue를 쓸 수 있는지는 이렇게 확인했었다.
hasattr(telegram.ext, "JobQueue") # True
True가 나왔으니 있다고 봤다. 이 검사가 알려 주는 것은 JobQueue라는 클래스가 모듈에 정의돼 있다는 것뿐이고, 클래스는 extra와 무관하게 늘 있다. 봐야 했던 것은 애플리케이션 객체에 큐가 만들어졌는지였다.
app.job_queue is None # True 였다
수정은 requirements 한 줄이다.
-python-telegram-bot>=21.6
+python-telegram-bot[job-queue]>=21.6
폴백이 있었던 탓에 이 문제는 조용했다. 주 경로가 한 번도 실행되지 않고 있다는 걸 폴백이 가리고 있었다.
일부러 열어 둔 패키지
모든 의존성에 상한을 건 것은 아니다. 외부 사이트에서 영상을 받아 오는 도구는 그 사이트가 바뀔 때마다 따라가야 해서 자주 갱신해야 한다. 이 패키지는 하한만 두고, requirements에 “고정 핀을 두지 않는 이유”를 주석으로 적어 두었다.
기준은 이렇게 잡았다. 오래된 버전이 깨질 가능성이 큰 패키지는 열어 두고, 새 버전이 깨뜨릴 가능성이 큰 패키지는 닫는다. 어느 쪽이든 이유를 그 줄 옆에 적는다.
requirements를 고칠 때 지금 하는 것
- 내가 import하지 않는 패키지라도 한 번 깨졌으면 requirements에 직접 적어 상한을 건다. 하한만 올리고 끝내지 않는다.
- 상한은 지금 설치된 버전에서 그 기능을 실제로 돌려 본 다음에 걸고, 왜 묶었는지와 언제 풀 수 있는지를 옆에 주석으로 남긴다.
- optional extra가 들어갔는지는
hasattr말고 런타임 값(app.job_queue is None)으로 본다. 폴백이 있는 경로는 주 경로가 실제로 도는지도 따로 확인한다.