버튼을 두 번 누르면 트레이스백 DM이 오던 봇 초안

Can't parse entities

사용자가 자유 입력에 _, *, [ 같은 문자를 넣으면 텔레그램이 400과 함께 이 메시지를 돌려줬고, 화면은 거기서 멈췄다.

커뮤니티용 텔레그램 봇에는 인라인 버튼으로 값을 고르고 자유 입력을 받아 저장하는 화면이 여럿 있다. 2026년 7월 초부터 중순까지 이 화면들의 오류 처리를 네 번 고쳤다. 처음에는 오류가 아무 흔적 없이 사라졌고, 그걸 고치자 오류가 아닌 것까지 알림으로 쏟아졌다.

저장은 끝났는데 사용자는 실패한 줄 알았다

멈추는 자리는 경로마다 달랐다. 어떤 경로에서는 저장하기 전에 죽어서 더 진행할 수 없는 막다른 상태가 됐다. 다른 경로에서는 저장은 끝났는데 그 뒤의 저장 확인 메시지가 깨졌다. 뒤쪽이 더 나빴다. 사용자는 실패한 줄 알고 같은 내용을 다시 제출했다.

원인은 단순했다. 메시지를 parse_mode="Markdown"으로 보내면서 사용자가 입력한 텍스트를 이스케이프 없이 끼워 넣고 있었다. 레거시 Markdown에서 _나 *는 서식의 시작이라, 짝이 맞지 않으면 텔레그램이 메시지 전체를 거절한다.

핸들러에서 예외가 나도 사용자에게는 아무 일도 일어나지 않았다. 버튼을 누르면 뜨는 로딩 표시가 풀리지 않은 채로 남았고 봇은 답이 없었다. PTB의 기본 동작이 그렇다. 에러 핸들러를 등록하지 않으면 PTB는 핸들러에서 올라온 예외를 로그에만 남긴다. 콜백 쿼리에 answer()를 하기 전에 예외가 나면 클라이언트의 로딩 표시는 그대로 남고, 사용자에게 가는 메시지는 없다. 서버 로그를 보지 않는 한 실패했다는 걸 아는 사람이 없다.

1차: 자른 다음에 이스케이프, 그리고 전역 핸들러

사용자 텍스트를 Markdown 문맥에 넣는 모든 지점에 이스케이프 헬퍼를 씌웠다.

from telegram.helpers import escape_markdown

def _md(s) -> str:
    # 사용자 텍스트를 레거시 Markdown(V1) 문맥에 안전하게 넣는다.
    # 반드시 자르기(_short) 이후에 적용한다.
    return escape_markdown(str(s or ""), version=1)

line = f"Current: _{_md(_short(value, 60))}_"

긴 값은 화면에 맞게 잘라서 보여 주는데, 이스케이프를 먼저 하고 자르면 이스케이프용 백슬래시와 그 뒤의 문자 사이가 잘릴 수 있다. 그래서 자른 다음에 이스케이프한다.

add_error_handler로 전역 핸들러도 등록했다. 이스케이프를 빠뜨린 곳이 더 있을 수 있고, 다른 종류의 예외도 같은 식으로 조용히 사라지고 있었을 것이기 때문이다. 핸들러는 스택트레이스를 로그에 남기고, 콜백이면 answer()로 로딩 표시를 풀고, 채팅에 문제가 생겼다는 안내를 보낸다. 안내는 서식 없는 plain text다. 오류 안내가 다시 파싱 오류를 내면 안 된다. 핸들러 본문 전체는 try/except로 감쌌다. 여기서 예외가 나면 받아 줄 곳이 없다.

2차: 로그가 재배포 때 사라져서 DM으로 받았다

전역 핸들러가 로그를 남기게 됐는데 정작 그 로그가 남아 있지 않았다. 봇은 컨테이너로 돌고 재배포가 잦다. 컨테이너 로그는 컨테이너를 새로 만들 때 사라진다. 사용자가 실패했다고 알려 줄 때쯤에는 트레이스백이 없었다.

그래서 전역 핸들러가 미처리 예외를 나에게 DM으로 보내게 했다. 누가 어떤 콜백 데이터를 눌렀는지와 트레이스백을 담는다. 트레이스백이 길면 앞을 자르고 끝을 남긴다. 실제 발생 지점이 끝에 있어서다. 같은 버그가 연쇄로 터질 때를 대비해 쿨다운도 넣었는데, 예외 타입과 트레이스백 마지막 두 줄을 서명으로 삼아 같은 서명은 5분 안에 한 번만 보낸다.

같은 수정에서 저장 흐름의 두 군데를 더 손봤다. 하나는 저장 뒤의 확인 메시지다.

# 여기까지 왔으면 저장은 이미 끝났다.
try:
    await q.edit_message_text(text, parse_mode="Markdown")
except BadRequest:
    logger.warning("confirm render failed, resend as plain text")
    await q.edit_message_text(text.replace("*", "").replace("_", ""))

저장이 성공한 뒤의 확인 메시지는 실패해도 저장 결과와 무관하다. 렌더링 실패가 저장 성공을 덮지 않도록, 파싱 400이 나면 서식 문자를 빼고 plain text로 다시 보낸다.

다른 하나는 핸들러 진입부의 answer()다. 봇이 재시작하는 사이에 누른 탭은 봇이 돌아온 뒤에 배달되는데, 그때 콜백 쿼리는 이미 만료돼 있어서 answer()가 “Query is too old”로 400을 던진다. 이 예외가 밖으로 나가면 저장 탭 하나가 통째로 사라진다. 쿼리가 만료됐어도 메시지 편집과 저장은 정상적으로 되므로, answer() 실패는 삼키고 계속 진행하게 했다.

3차는 하루 만에 접었다

DM을 보내기 시작하고 며칠 뒤, 오는 DM 중에 버그가 아닌 것이 섞여 있다는 걸 알았다. 버튼을 한 번 더 누르거나 오래된 버튼을 누르는 것만으로 트레이스백 DM이 연달아 왔다.

이미 반영된 상태에서 같은 버튼을 다시 누르면, 봇은 같은 내용으로 메시지를 다시 그리려 하고 텔레그램은 “Message is not modified”로 거절한다. 재시작 전에 만들어진 오래된 버튼을 누르면 answer()가 “Query is too old”로 실패한다. 둘 다 사용자 입장에서는 잘못된 것이 없다. 화면은 이미 원하는 상태이거나, 만료 안내를 받으면 되는 상황이다. 그런데 전역 핸들러는 이것을 미처리 예외로 보고, 사용자에게는 문제가 생겼다는 엉뚱한 경고를, 나에게는 트레이스백 DM을 보냈다.

3차 수정에서는 문제가 보인 핸들러 두 곳에 try/except를 넣어 해당 메시지의 BadRequest만 삼켰다. 하루 뒤에 이 방식을 접었다. 세어 보니 같은 방어가 없는 콜백 호출이 253곳이었다. 메시지를 편집하거나 answer()를 부르는 곳마다 같은 예외가 날 수 있는데, 한 곳씩 감싸는 건 끝이 없고 새 핸들러를 만들 때마다 빠뜨릴 일이었다.

4차: 전역 핸들러 맨 앞에서 거른다

_BENIGN_BADREQUEST_MARKERS = (
    "message is not modified",
    "query is too old",
    "query id is invalid",
    "message to edit not found",
    "message to delete not found",
    "message can't be edited",
)

def _is_benign_badrequest(err) -> bool:
    if not isinstance(err, BadRequest):
        return False
    msg = str(err).lower()
    return any(m in msg for m in _BENIGN_BADREQUEST_MARKERS)

여섯 가지는 세 부류다. 같은 화면을 다시 그리려 한 경우, 버튼이 오래된 경우, 원래 메시지가 이미 지워졌거나 편집할 수 없는 경우. 전역 핸들러는 예외가 이 부류에 들면 info 로그 한 줄만 남기고 바로 반환한다. 사용자 경고도 소유자 DM도 없다. 그 밖의 예외는 전과 똑같이 처리된다.

오류 메시지 문자열을 비교하는 방식이 깔끔하지는 않다. 다만 이 경우들은 모두 같은 BadRequest 타입으로 올라와서, 타입만으로는 진짜 버그인 400과 구별할 수 없다.