Paper 서버가 자꾸 구버전으로? PaperMC 구 다운로드 API(v2) 종료 총정리 (Fill v3 대응법)

안녕하세요! Mojangcam입니다 😎

혹시 요즘 Paper 서버를 돌리는데 자동 업데이트가 자꾸 구버전을 받아오거나, 아예 다운로드가 실패하지 않나요? 여러분 잘못이 아니에요! 2026년 7월 1일부터 PaperMC의 구 다운로드 API(v2)가 완전히 종료되면서, AMP·도커·자작 스크립트 등 옛날 API를 쓰던 자동 업데이터들이 줄줄이 멈추고 있거든요. 오늘은 이 이슈의 원인부터 새 API(Fill v3) 대응 방법까지, 복붙 가능한 코드와 함께 총정리해볼게요!

📌 증상 - 이런 일이 생기고 있어요

서버 패널(AMP 등)의 "업데이트" 버튼을 눌러도 최신 빌드가 아닌 작년 12월 빌드가 설치돼요.
api.papermc.io/v2/... 를 호출하던 스크립트가 404 에러를 뱉으며 실패해요.
도커 이미지(itzg/docker-minecraft-server 등)에서 TYPE=PAPER로 새 버전을 받으려는데 실패하거나 구버전이 받아져요.

실제로 AMP 패널의 Paper 업데이터가 폐기된 v2 API를 사용해 새 빌드를 못 가져오는 이슈가 공식 깃허브에 올라와 있고, 도커 이미지 쪽도 새 Fill API 지원 작업이 진행됐어요. 자작 업데이트 스크립트를 쓰는 분들은 100% 해당되는 이슈예요.

🧠 원인 - v2 API가 완전히 문을 닫았어요

PaperMC가 다운로드 서비스를 Fill이라는 새 시스템으로 전면 교체했어요. 타임라인을 보면 이래요.

날짜	무슨 일이?
2025-12-31	v2 API(`api.papermc.io/v2`)에 신규 빌드 공급 중단 → 이때부터 구버전만 받아짐
2026-07-01	v2 API 완전 차단 → 이제 호출 자체가 안 됨

그러니까 올해 상반기에 "어? 최신 빌드가 안 올라오네?" 했던 게 전조였고, 7월 1일부터는 아예 접속이 안 되는 거예요. 이제 유일한 공식 경로는 Fill v3 API(fill.papermc.io)입니다.

📌 해결법 1 - 일단 급하면 수동 다운로드

가장 빠른 응급처치예요. PaperMC 공식 다운로드 페이지에서 최신 jar를 직접 받아서 서버 폴더의 jar를 교체하면 돼요. 자동화가 급하지 않은 소규모 서버라면 이걸로 충분해요.

📌 해결법 2 - 스크립트를 Fill v3 API로 교체하기

자동 업데이트 스크립트를 쓰신다면 이제 Fill v3로 갈아타야 해요. v2와 달라진 핵심 포인트 3가지부터 하나씩 뜯어볼게요 💡

User-Agent 필수 : 이제 모든 요청에 자기 소프트웨어를 식별할 수 있는 User-Agent 헤더(연락처 이메일이나 URL 포함)를 넣어야 해요. generic한 값이면 거부되거나 속도 제한이 걸릴 수 있어요.
다운로드 키 변경 : v2의 application → v3에서는 server:default, mojang-mappings → server:mojang 으로 바뀌었어요.
URL 직접 조립 금지 : 다운로드 URL이 API 응답 안에 통째로 들어있고(새 도메인 fill-data.papermc.io), 형식이 바뀔 수 있어서 직접 조립하지 말라고 공식 문서에서 안내해요.

먼저 curl로 최신 빌드 정보를 확인해볼게요.

nginx

# Fill v3 API - 최신 빌드 조회 (User-Agent 필수!)
curl -s -H "User-Agent: my-updater/1.0 (contact@example.com)" \
  "https://fill.papermc.io/v3/projects/paper/versions/1.21.11/builds/latest"

응답 JSON의 downloads 안에 있는 server:default 항목의 url이 실제 다운로드 주소예요. 참고로 Fill은 REST 말고 GraphQL(https://fill.papermc.io/graphql)도 지원하는데, 일반적인 업데이트 용도라면 REST로 충분해요.

📌 전체 코드 (복붙 OK) - 파이썬 자동 업데이터

코드

# Python 3.8+ / requests 2.x (pip install requests)
# PaperMC Fill v3 API로 최신 Paper 빌드를 받는 스크립트
import requests

# 자기 정보로 꼭 바꿔주세요! (User-Agent 미설정 시 거부될 수 있어요)
HEADERS = {"User-Agent": "mojangcam-updater/1.0 (/)"}
BASE = "https://fill.papermc.io/v3/projects/paper"

# 1) 지원 버전 목록에서 최신 버전 확인
project = requests.get(BASE, headers=HEADERS, timeout=10).json()

# 2) 원하는 마인크래프트 버전 지정 (예: 1.21.11)
version = "1.21.11"

# 3) 해당 버전의 최신 빌드 정보 조회
build = requests.get(
    f"{BASE}/versions/{version}/builds/latest",
    headers=HEADERS, timeout=10,
).json()

# 4) 응답에 포함된 다운로드 URL로 jar 저장 (URL 직접 조립 금지!)
dl = build["downloads"]["server:default"]
print(f"채널: {build.get('channel')} / 파일: {dl['name']}")

jar = requests.get(dl["url"], headers=HEADERS, timeout=60)
with open("paper.jar", "wb") as f:
    f.write(jar.content)
print("다운로드 완료! ✅")

하나씩 뜯어볼게요 💡

HEADERS : Fill v3의 필수 조건이에요. 소프트웨어 이름 + 버전 + 연락처(URL/이메일) 형태로 적어주세요.
builds/latest : 해당 버전의 가장 최신 빌드 하나만 딱 받아오는 엔드포인트예요.
channel : 빌드 안정성 채널이에요. ALPHA(불안정) → BETA → STABLE(운영 서버용) → RECOMMENDED 순으로 안정적이니, 실서버는 STABLE 이상만 쓰는 걸 권장해요.
downloads["server:default"] : v2의 application에 해당하는 새 키예요. 여기 들어있는 url을 그대로 쓰면 돼요.

📌 실행 결과

코드

채널: STABLE / 파일: paper-1.21.11-XX.jar
다운로드 완료! ✅

📌 해결법 3 - 패널·도커 쓰는 분들은 업데이트 확인

직접 스크립트를 짜지 않는 분들은 쓰고 있는 툴이 Fill 대응을 했는지 확인하고 최신 버전으로 올려주세요.

itzg/docker-minecraft-server : Fill API 지원이 반영됐으니 이미지를 최신으로 pull 하세요.
AMP(CubeCoders) : v2 API 이슈가 보고돼 있으니 패널 업데이트 공지를 확인하고, 급하면 해결법 1(수동 교체)로 버티세요.
자작 쉘스크립트 : 위 파이썬 코드나 curl 방식으로 교체하세요.

💡 보너스 - 요즘 Paper 버전이 26.x인 이유

2026년부터 마인크래프트와 Paper가 연도 기반 버전 체계로 바뀌었어요. "연도.드롭번호" 형식이라 26.1, 26.2처럼 올라가고, 빌드는 26.1.2.build.23-alpha처럼 상태까지 붙어요. 지금 26.2는 알파 채널 빌드가 올라오는 단계라, 운영 서버는 아직 26.1 안정 빌드나 1.21.x 유지가 안전해요. 새 빌드 상황은 위 스크립트의 channel 값으로 확인하면 됩니다!

📌 자주 나는 에러

403 Forbidden / 요청 거부 — 원인: User-Agent가 없거나 curl/8.0 같은 generic 값 → 해결: 소프트웨어명 + 연락처가 들어간 User-Agent 헤더 추가.
404 Not Found (api.papermc.io/v2) — 원인: 종료된 v2 엔드포인트 호출 → 해결: fill.papermc.io/v3로 URL 교체 + 응답 구조(downloads["server:default"])에 맞게 파싱 수정.
KeyError: 'application' — 원인: v2 시절 키 이름을 그대로 사용 → 해결: application → server:default, mojang-mappings → server:mojang 으로 변경.

📌 마무리

오늘은 7월 1일부로 종료된 PaperMC v2 다운로드 API와 새 Fill v3 대응법을 정리해봤어요. 요약하면 ① v2는 이제 완전히 죽었고 ② Fill v3는 User-Agent 필수 + server:default 키 + 응답에 든 URL 사용, ③ 패널·도커 유저는 툴 업데이트 확인! 이렇게 기억해주세요.

다음 글에서는 마인크래프트 플러그인 개발환경 세팅(IntelliJ + Paper), 그다음엔 Paper로 서버 여는 법(최신 버전 기준)을 다룰 예정이에요. 서버 운영하시는 분들은 시리즈로 이어보시면 딱 좋아요. 기대해주세요 🙌