[Cloudflare Pages] 100개 초과 배포 삭제 불가 버그 트러블슈팅 (API 에러 디버깅)

1. 문제 상황 (What was the error?)

Cloudflare Pages를 사용해 여러 번 배포(Deployments)를 진행하다 보면 과거의 내역이 쌓이게 됩니다. 그런데 이 배포 내역이 100개를 초과하면 대시보드 상에서 프로젝트를 정상적으로 삭제하거나 관리할 수 없는 알려진 버그가 존재합니다.

Cloudflare 측에서 안내하는 해결책은 공식으로 제공하는 delete-all-deployments NPM 스크립트를 로컬에서 구동하여 배포 기록을 스크립트로 일괄 삭제하는 것입니다.

하지만 가이드에 따라 터미널에서 환경 변수를 넣고 스크립트를 실행했음에도 불구하고, 다음과 같이 삭제가 진행되지 않고 에러가 발생했습니다.

Error: Could not fetch deployments for [나의_도메인명]
    at listDeploymentsPerPage (/home/.../delete-all-deployments/index.js:73:11)

2. 원인 파악 (What to check?)

에러 메시지만 보면 단순 네트워크 연결 문제나 일시적인 에러처럼 보일 수 있으나, 스크립트 내부 코드를 분석하고 통신 중인 Cloudflare API를 스크립트를 거치지 않고 직접 curl로 호출해보니 진짜 응답 에러를 확인할 수 있었습니다.

{
  "code": 8000007,
  "message": "Project not found. The specified project name does not match any of your existing projects."
}

오류의 진짜 원인은 터미널에서 스크립트에 주입한 환경 변수 중 --CF_PAGES_PROJECT_NAME에 서비스 중인 커스텀 도메인명(예: example.com 또는 jmlee.net)을 눈으로 보고 입력했던 것이 문제였습니다.

스크립트가 내부적으로 사용하는 API가 요구하는 값은 퍼블릭 도메인이 아니라, Cloudflare Pages 대시보드에서 프로젝트를 처음 생성할 때 부여된 고유 프로젝트 이름(예: my-quartz-blog, my-project-name 등)이어야 했습니다.

3. 해결 방법: 올바른 환경변수 찾기 (How it was solved)

문제를 해결하려면 명령어를 실행할 때 주입하는 3가지 파라미터를 정확하게 식별해야 합니다.

🔑 필수 정보 3가지 확인 방법

CF_API_TOKEN:
- Cloudflare 대시보드 우측 상단 유저 아이콘 > My Profile > API Tokens에서 새 토큰을 발급하여 사용합니다.
- 주의할 점은 토큰 권한을 설정할 때 반드시 Cloudflare Pages Edit 권한을 부여해야 스크립트가 배포 기록을 삭제할 수 있습니다.
CF_ACCOUNT_ID:
- Cloudflare 도메인 관리 화면의 우측 하단(API 텍스트 하단 탭)에서 확인할 수 있습니다.
- URL 주소창의 dash.cloudflare.com/[여기에 있는 영문/숫자 조합]/pages... 경로에서도 확인 가능합니다.
CF_PAGES_PROJECT_NAME (가장 중요):
- 에러의 주원인이었던 프로젝트 이름입니다. 도메인 주소를 쓰시면 안 됩니다!
- Cloudflare 대시보드 좌측 Pages (또는 Workers & Pages) 메뉴에 들어갔을 때 목록에 표시되는 해당 프로젝트의 이름 자체를 적어야 합니다.

🚀 명령어 재실행

정확한 정보 3가지를 모두 찾았다면, NPM 스크립트가 설치된 폴더로 돌아와 올바른 변수를 세팅한 뒤 다시 실행합니다.

cd delete-all-deployments

CF_API_TOKEN="발급받은_토큰" \
CF_ACCOUNT_ID="어카운트_ID" \
CF_PAGES_PROJECT_NAME="my-pages-project" \
npm start

정확한 고유 프로젝트명을 입력하면 드디어 정상적으로 API가 호출되며, 현재 운영 중인 라이브(프로덕션) 배포를 제외한 과거의 모든 배포 내역들이 하나씩 순차적으로 삭제됩니다. 모두 삭제되고 나면 100개 제한 오류가 완전히 풀리게 됩니다! 🎉

4. 마무리 및 교훈 (Takeaway)

Cloudflare 등 클라우드 컨트롤용 CLI/스크립트에서 404 혹은 찾지 못한다는 에러가 날 경우, 시스템이 요구하는 값이 사용자용 퍼블릭 도메인명인지 **내부 고유 식별자(프로젝트명, ID)**인지 반드시 한 번 더 교차 검증하는 습관을 들여야 합니다.
종종 CLI 툴들이 API의 구체적인 에러(Project not found)를 잡아 통짜 에러 구문(Could not fetch deployments)으로 덮어씌워서 출력하곤 합니다. 이런 래핑 처리가 디버깅을 어렵게 만들 때가 있는데, 이럴 땐 코드를 뜯어보고 **원본 API를 직접 호출(Raw Call)**해보는 것이 가장 빠른 지름길입니다.

1. 문제 상황 (What was the error?)​

2. 원인 파악 (What to check?)​

3. 해결 방법: 올바른 환경변수 찾기 (How it was solved)​

🔑 필수 정보 3가지 확인 방법​

🚀 명령어 재실행​

4. 마무리 및 교훈 (Takeaway)​