Cloudflare 오류 1101 Worker 예외 해결

Problem

Cloudflare Worker를 통해 서빙되는 페이지가 Error 1101: Worker threw exception(또는 “Rendering error”)을 반환합니다. 요청은 Cloudflare 엣지에 닿았고 Worker가 돌았지만, Worker 자신의 코드가 응답을 반환하기 전에 실패했습니다.

Symptoms

• Cloudflare 오류 페이지에 520–526 오리진 오류가 아니라 1101 “Worker threw exception”이 표시됩니다.
• HTTP 진단이 그 URL에 Cloudflare 브랜드 5xx 페이지를 반환하고, 어느 네트워크에서든 재현됩니다.
• 어떤 경로·어떤 입력에서만 실패하고 다른 데선 멀쩡합니다 — 특정 경로, 특정 쿼리스트링, 로그인한 사용자.
• 오리진 서버 로그에는 아무것도 없습니다. 요청이 엣지를 떠난 적이 없으니까요.

What 1101 Actually Means

Worker는 앱 앞에 서 있는 프록시가 아닙니다 — 자신이 맡은 경로에 대해 Worker가 곧 앱이고, Cloudflare 엣지 런타임에서 돕니다. 그래서 1101은 네트워크 문제가 아닙니다. 잡히지 않은 예외를 던진 자바스크립트, 아무도 catch하지 않은 rejected promise, 그리고 — 교묘한 변종 — 일을 다 끝냈는데 끝내 Response를 돌려주지 않은 코드입니다.

이 마지막 경우엔 뚜렷한 지문이 있습니다. 요청에 묶인 코드가 전부 실행되고 이벤트 루프가 비었는데도 Response가 돌아오지 않으면, Cloudflare 런타임은 “the script will never generate a response”라고 보고합니다. 흔한 범인은 resolve도 reject도 되지 않는 promise를 await한 경우입니다: 멈춰버린 서브요청 fetch(), await을 빼먹은 바인딩, resolve로 가는 길이 없는 방치된 new Promise.

바로 이 때문에 1101은 오진됩니다. 5xx처럼 보이니 사람들은 죽은 서버를 찾으러 갑니다. 하지만 520–524 코드는 Cloudflare가 오리진과 대화했는데 답이 마음에 안 든 것이고, 1101은 오리진과의 대화 자체가 없었던 것 — 엣지 코드가 죽은 것입니다. 오리진을 쫓는 건 엉뚱한 가로등 밑을 뒤지는 격입니다.

Top 3 Causes

1. 특정 코드 경로의 잡히지 않은 예외 - Worker가 한 경로, 한 입력 형태, 한 분기에서 던집니다 — 잘못된 본문에 대한 JSON.parse, undefined가 되는 배열 인덱스, 배열이 아닌 것에 대한 .map. 정상 경로는 잘 돌아 테스트를 통과했고, 프로덕션 트래픽만 그 나쁜 분기에 닿습니다. 1101이 전면 장애가 아니라 간헐적인 경우가 많은 이유입니다.
2. 누락되거나 이름이 틀린 바인딩 - 코드가 env.MY_KV나 env.DB를 읽는데, 배포에 바인딩이 추가된 적이 없거나 wrangler.toml의 이름이 코드의 이름과 일치하지 않습니다. 참조는 undefined이고, 거기에 대한 첫 메서드 호출이 던지며, 그걸 건드리는 모든 요청이 1101이 됩니다.
3. 끝내 settle되지 않는 promise - 타임아웃 없이 await한, 느리거나 죽은 업스트림으로의 서브요청 fetch(), 또는 resolve가 빠진 수제 promise. Worker는 던지지 않고 — 그냥 반환하지 않으며, 런타임이 “the script will never generate a response”로 표면화합니다.

Diagnose with DechoNet

• HTTP 진단으로 1101이 결정론적인지 확인하세요. 우리 쪽 자동 요청도 그 실패 URL에 매번 Cloudflare 오류를 돌려받는다면, 예외는 그 요청 형태에서 발생하는 것 — 같은 메서드·경로·헤더로 로컬에서 재현하세요. HTTP 진단은 성공하는데 당신에겐 특정 경로만 실패한다면, 버그는 경로·입력 고유이고, 바로 그 요청을 wrangler tail에 먹이면 됩니다.
• DNS 진단으로 그 호스트명이 실제로 Cloudflare를 통해 프록시(오렌지 구름)되는지 확인해 Worker가 경로에 있기라도 한지 알아보세요 — 회색 구름 레코드는 Worker를 아예 건너뛰어 1101을 배제합니다.

Resolution Checklist

• 실제 예외를 읽으세요. wrangler tail(또는 대시보드의 Workers 실시간 로그)을 켜고 요청을 재현합니다. 스택 트레이스가 exceptions 필드에 나타납니다 — 그 줄 번호가 당신의 버그입니다.
• 결정론적으로 재현하세요. HTTP 진단이 1101을 유발하는 정확한 경로·메서드·페이로드를 적어두고, wrangler dev로 로컬에서 재생하세요.
• 모든 바인딩을 감사하세요. 코드가 읽는 각 env.*가 wrangler.toml에 동일한 이름으로 선언됐는지, KV/D1/R2 바인딩이 로컬만이 아니라 배포된 환경에 존재하는지 확인하세요.
• 위험한 작업을 try/catch와 타임아웃으로 감싸세요. JSON.parse, 외부 fetch(), 사용자 입력을 파싱하는 모든 걸 가드하고, 죽은 업스트림이 Worker 전체를 멈추지 못하도록 abort 타임아웃 없이 서브요청을 절대 await하지 마세요.
• 1102와 1027을 먼저 배제하세요. 메시지가 “exceeded resource limits”면 크래시가 아니라 CPU/메모리 문제이고, “daily request limit exceeded”면 UTC 자정까지 Free 요금제 쿼터가 소진된 것입니다. 둘 다 로직을 고쳐서 풀리지 않습니다.
• 재배포하고 계속 tail하세요. 수정을 푸시하고, 실제 트래픽에서 exceptions 필드가 비어 있는지 지켜본 뒤에야 종료로 판단하세요.

When to Escalate

• wrangler tail에 예외가 전혀 안 뜨는데도 요청이 계속 1101이면, 오류 페이지의 요청 ID(Ray ID)를 캡처해 Cloudflare 티켓을 여세요 — 런타임 쪽 문제는 드물지만 있고, Ray ID가 그 요청을 추적하게 해줍니다.
• 예외가 Worker에 번들된 서드파티 라이브러리/SDK 안으로 이어진다면, 스택 트레이스를 들고 그 패키지 관리자에게 에스컬레이션하세요. 엣지 런타임엔 일부 Node API가 없어서, Node 전역을 가정한 라이브러리는 당신 코드는 절대 내지 않을 방식으로 던집니다.