터미널에 wrangler deploy를 입력하고 엔터를 누르는 그 짧은 순간, 괜히 긴장되는 건 저만 그런 게 아닐 겁니다. 로컬에서 wrangler dev로 테스트할 때는 분명히 잘 돌아갔거든요. 그런데 배포만 하면 빨간 에러가 쏟아지는 상황. 처음 겪었을 때 솔직히 멘탈이 좀 흔들렸습니다. 에러 메시지를 복사해서 구글에 붙여넣기를 반복한 시간만 해도 꽤 될 겁니다.
그때의 삽질을 바탕으로, wrangler deploy 실패 시 자주 등장하는 에러 유형별로 원인과 해결법을 정리해 봤습니다.
📑 목차
자주 발생하는 에러 메시지 유형
wrangler deploy 실패는 에러 메시지만 제대로 읽어도 원인의 절반은 파악됩니다. 문제는 처음 보면 메시지가 너무 불친절하다는 거지만요. 관련해서 Cloudflare Workers fetch() 네트워크 에러 해결법 글도 참고하면 도움이 됩니다.
인증 관련 에러
✘ [ERROR] A request to the Cloudflare API
(/accounts/xxxxxxxx/workers/scripts/my-worker) failed.
Authentication error [code: 10000]
이 메시지는 Cloudflare API와의 인증에 실패했다는 뜻입니다. 처음 봤을 때 “아니, 방금 로그인했는데?” 하면서 당황했던 기억이 납니다. API 토큰이 만료되었거나, 토큰에 Workers 스크립트 편집 권한이 없거나, 로그인 자체가 안 된 상태에서 나타납니다.
wrangler.toml 설정 에러
✘ [ERROR] Processing wrangler.toml configuration:
- "compatibility_date" is required in your wrangler.toml file.
Please add a compatibility_date to your wrangler.toml file.
wrangler.toml 파일에 필수 항목이 누락된 경우입니다. 이 에러는 그나마 친절한 편이에요. 뭐가 빠졌는지 정확히 알려주니까요. compatibility_date가 가장 흔하지만, name이나 main 경로가 잘못되어도 비슷한 에러가 발생합니다.
빌드 실패 에러
✘ [ERROR] Could not resolve "node:crypto"
Build failed with 1 error:
src/index.ts:1:23: ERROR: Could not resolve "node:crypto"
이 에러 때문에 키보드를 좀 세게 내려친 적이 있습니다. 분명 Node.js에서는 잘 되는 코드인데 Workers에서만 안 되거든요. Workers는 Node.js가 아닌 독자적인 V8 기반 런타임이라서, 일부 Node.js API는 별도 설정 없이는 사용할 수 없습니다.
스크립트 크기 초과 에러
✘ [ERROR] A request to the Cloudflare API
(/accounts/xxxxxxxx/workers/scripts/my-worker) failed.
Script startup exceeded CPU time limit. [code: 10021]
무료 플랜 기준 Workers 스크립트는 압축 후 1MB, CPU 실행 시간 10ms라는 제한이 있습니다. “설마 이 정도가 1MB를 넘겠어?” 하고 방심하다가 만나는 에러입니다. 무거운 npm 패키지 하나만 포함해도 순식간에 초과합니다.
에러별 원인 분석
위 에러들의 근본 원인을 하나씩 짚어보겠습니다.
인증 에러의 주요 원인 3가지: 첫째, wrangler login으로 발급받은 OAuth 토큰이 만료된 경우입니다. 브라우저 인증 방식은 일정 시간이 지나면 재인증이 필요합니다. 둘째, 환경변수 CLOUDFLARE_API_TOKEN에 설정한 토큰의 권한 범위가 부족한 경우입니다. Workers 배포에는 최소한 “Workers Scripts: Edit” 권한이 필요한데, 저는 처음에 “Read” 권한만 줘놓고 왜 안 되나 30분을 헤맨 적이 있습니다. 솔직히 좀 허무했어요. 셋째, 여러 Cloudflare 계정을 사용하는 환경에서 다른 계정의 토큰이 적용되는 경우입니다.
wrangler.toml 에러의 핵심: 대부분 프로젝트 초기 세팅에서 발생합니다. wrangler init으로 생성한 템플릿을 수정하다가 실수로 필수 항목을 지우는 경우가 많습니다. TOML 문법은 YAML과 달리 들여쓰기에 민감하지 않지만, 따옴표 누락이나 섹션 헤더 오타에는 엄격합니다.
빌드 에러의 본질: Workers 런타임은 웹 표준 API(Fetch, Streams, Web Crypto 등)를 기본 지원하지만, Node.js 전용 모듈(fs, net, child_process 등)은 기본적으로 사용할 수 없습니다. 이걸 처음 알았을 때 “그럼 대체 뭘 쓰라는 거지…” 하고 잠깐 막막했는데, 다행히 Cloudflare가 Node.js 호환성을 점차 확대하고 있어서 node_compat 플래그로 상당수 모듈을 활성화할 수 있습니다.
단계별 해결 방법
1단계: 인증 상태 확인 및 재로그인
가장 먼저 현재 인증 상태를 확인합니다. 이것부터 확인하는 습관을 들이면 불필요한 삽질 시간을 확 줄일 수 있습니다.
# 현재 로그인된 계정 확인
wrangler whoami
# 출력 예시 (정상)
# ⛅️ wrangler 3.x.x
# Getting User settings...
# 👋 You are logged in with an OAuth Token, associated with the email [email protected]!
# ┌─────────────────────┬──────────────────────────────────┐
# │ Account Name │ Account ID │
# ├─────────────────────┼──────────────────────────────────┤
# │ My Account │ abcdef1234567890abcdef1234567890 │
# └─────────────────────┴──────────────────────────────────┘
You are not authenticated.라고 뜨면 로그인이 필요합니다.
# 브라우저 기반 OAuth 로그인
wrangler login
# 또는 API 토큰을 직접 환경변수로 설정
export CLOUDFLARE_API_TOKEN="your-api-token-here"
API 토큰을 사용하는 경우, Cloudflare 대시보드에서 토큰을 생성할 때 아래 권한을 반드시 포함해야 합니다. 저처럼 Read만 주고 삽질하는 일이 없으시길 바랍니다.
- Account > Workers Scripts > Edit — 스크립트 배포 필수 권한
- Account > Workers KV Storage > Edit — KV 네임스페이스를 사용하는 경우
- Account > Workers Routes > Edit — 커스텀 라우트를 설정하는 경우
- Zone > Workers Routes > Edit — 특정 도메인에 Worker를 바인딩하는 경우
2단계: wrangler.toml 필수 항목 점검
정상 작동하는 최소 구성의 wrangler.toml은 다음과 같습니다. 이걸 하나의 “안전한 기본값”으로 저장해두고 새 프로젝트마다 복사해서 쓰면 편합니다.
name = "my-worker"
main = "src/index.ts"
compatibility_date = "2026-03-15"
compatibility_flags = ["nodejs_compat"]
# KV 바인딩 (필요한 경우)
[[kv_namespaces]]
binding = "MY_KV"
id = "your-kv-namespace-id-here"
# 환경변수 (민감하지 않은 값)
[vars]
ENVIRONMENT = "production"
# Cron Trigger (필요한 경우)
[triggers]
crons = ["0 0 * * *"]
자주 놓치는 실수들입니다.
name에 대문자, 공백, 특수문자가 들어가 있지 않은지 — 소문자, 숫자, 하이픈만 허용됩니다. 저는 한번 언더스코어(_)를 넣었다가 에러 나서 한참 찾은 적 있습니다main경로가 실제 엔트리포인트 파일 위치와 일치하는지 — 상대 경로 기준입니다compatibility_date가 유효한 날짜 형식(YYYY-MM-DD)인지- KV 바인딩의
id가 대시보드에서 확인한 값과 정확히 일치하는지
KV 네임스페이스 ID는 CLI로도 조회할 수 있습니다.
# KV 네임스페이스 목록 조회
wrangler kv namespace list
3단계: 빌드 에러 해결
배포 전에 로컬에서 빌드가 정상인지 먼저 확인합니다. 이 단계를 건너뛰고 바로 deploy를 하는 건… 솔직히 저도 가끔 합니다만, 높은 확률로 후회하게 됩니다.
# TypeScript 타입 체크
npx tsc --noEmit
# 로컬 개발 서버로 테스트
wrangler dev
wrangler dev에서 정상 동작하는데 wrangler deploy에서만 실패한다면, 주로 환경 차이가 원인입니다. 로컬에서는 Node.js 런타임이 일부 보완해주는데, 실제 Workers 엣지 런타임에서는 그렇지 않거든요. 이 미묘한 차이 때문에 “로컬에서는 되는데요?”라는 클래식한 대사를 하게 됩니다.
Node.js 내장 모듈이 필요한 경우, compatibility_flags를 활용합니다.
# wrangler.toml에 추가
compatibility_flags = ["nodejs_compat"]
이 플래그를 활성화하면 node:crypto, node:buffer, node:util 등 상당수의 Node.js 모듈을 사용할 수 있습니다. 이 한 줄을 몰라서 2시간을 날린 적이 있는데, 알고 나니까 너무 허무하더군요. 다만 node:fs, node:net, node:child_process처럼 OS 레벨 접근이 필요한 모듈은 Workers 환경의 특성상 지원되지 않습니다.
4단계: 번들 크기 최적화
스크립트 크기 제한에 걸리는 경우, 먼저 현재 번들 크기를 확인합니다.
# 실제 배포 없이 빌드 결과물만 확인
wrangler deploy --dry-run --outdir dist
# 번들 크기 확인
ls -lh dist/
크기를 줄이는 실전 방법들입니다.
- 무거운 라이브러리 교체:
moment.js(~300KB) 대신dayjs(~7KB)를 쓰면 극적으로 줄어듭니다.lodash전체를 import하는 대신lodash-es에서 필요한 함수만 가져오는 것도 효과적입니다 - Tree-shaking 활용: ESM(import/export) 형식을 사용하면 번들러가 사용하지 않는 코드를 자동 제거합니다
- package.json 점검:
dependencies에 개발용 패키지가 섞여 있지 않은지 확인하세요. jest나 eslint 같은 건devDependencies에 있어야 합니다
추가 팁과 예방법
wrangler 버전 관리
wrangler 버전이 오래되면 예상치 못한 에러가 발생할 수 있습니다. 특히 v2에서 v3으로 넘어가면서 설정 파일 구조가 일부 변경되었기 때문에, 작년에 쓰인 블로그 글을 따라하다가 에러를 만나는 경우가 꽤 있습니다.
# 현재 버전 확인
wrangler --version
# 최신 버전으로 업데이트
npm install -g wrangler@latest
배포 전 체크리스트
매번 배포하기 전에 아래 순서로 점검하면, 대부분의 실패를 미리 방지할 수 있습니다. 귀찮아 보여도 이 루틴을 따르면 진짜 삽질 시간이 확 줄어듭니다.
# 1. 인증 상태 확인
wrangler whoami
# 2. 타입 체크
npx tsc --noEmit
# 3. 로컬 테스트
wrangler dev
# 4. 드라이런으로 번들 확인
wrangler deploy --dry-run --outdir dist
# 5. 실제 배포
wrangler deploy
CI/CD 환경에서의 주의점
GitHub Actions 등 CI 환경에서 배포할 때는 CLOUDFLARE_API_TOKEN을 시크릿으로 설정해야 합니다. wrangler login은 브라우저가 필요하므로 CI에서는 사용할 수 없고, 반드시 API 토큰 방식을 써야 합니다. 또한 CLOUDFLARE_ACCOUNT_ID도 함께 설정해두면 여러 계정 간 혼선을 방지할 수 있습니다.
마무리
wrangler deploy 실패는 대부분 인증, 설정 파일, 빌드, 크기 제한 이 네 가지 중 하나가 원인입니다. 에러 메시지의 코드 번호([code: 10000], [code: 10021] 등)를 보고 원인을 좁혀가면 생각보다 빠르게 해결할 수 있습니다. 배포 전에 wrangler whoami와 --dry-run을 습관처럼 돌리는 것, 이것만 해도 새벽에 에러 때문에 잠 못 이루는 일은 많이 줄어들 겁니다. 자세한 내용은 Cloudflare Wrangler deploy 공식 문서에서 확인할 수 있습니다.