Skip to content

fix(server): migrate PaperDownloader to PaperMC v3 (fill) API - #428

Merged
okafke merged 1 commit into
headlesshq:paper-fill-apifrom
ChipWolf:fix/papermc-v3-fill-api
Jul 13, 2026
Merged

fix(server): migrate PaperDownloader to PaperMC v3 (fill) API#428
okafke merged 1 commit into
headlesshq:paper-fill-apifrom
ChipWolf:fix/papermc-v3-fill-api

Conversation

@ChipWolf

Copy link
Copy Markdown
Member

Problem

PaperMC sunset the v2 API (api.papermc.io/v2); it now returns HTTP 410. PaperDownloader still calls it, so server add paper <version> fails, breaking runServerIntegrationTest (in the build job) and the server-test jobs on every branch and PR:

java.io.IOException: Failed to get https://api.papermc.io/v2/projects/paper/versions/1.21/, response 410:
  {"ok":false,"error":"sunset","message":"This API version has been sunset ..."}
    at ...PaperDownloader.getBuild(PaperDownloader.java:36)

(Purpur, on a different API, still downloads fine in the same test — it's specifically Paper's v2 endpoint that's dead.)

Fix

Switch to PaperMC's current v3 "fill" API (fill.papermc.io/v3). Two shape changes vs v2:

  1. GET /v3/projects/paper/versions/{version}/builds returns a top-level array ordered newest-first (v2 returned { "builds": [...] } oldest-first). So the latest build is builds[0], not the last element.
  2. Each build carries a ready-made download URL at downloads."server:default".url, so the jar URL no longer needs to be templated.

Verification

  • :headlessmc-launcher:compileJava passes.
  • Verified against the live API that both code paths resolve correctly: the latest-build path (builds[0]) and an explicit-build lookup both yield a valid server:default URL that serves a real application/java-archive (HTTP 200). v2 confirmed returning 410.
  • End-to-end coverage is the existing runServerIntegrationTest (server add paper), which this unblocks.

Context

Surfaced while getting Minecraft 26.2 support green (headlesshq/mc-runtime-test#137, #426). This server-side failure is independent of the 26.2 lwjgl work but was reddening the build check on those PRs.

🤖 Generated with Claude Code

PaperMC sunset the v2 API (api.papermc.io/v2); it now returns HTTP 410,
so `server add paper <version>` fails and the server integration test
(runServerIntegrationTest) and server-test jobs break on every branch:

    java.io.IOException: Failed to get
      https://api.papermc.io/v2/projects/paper/versions/1.21/, response 410:
      {"ok":false,"error":"sunset", ...}

Switch to the current v3 "fill" API (fill.papermc.io/v3). Two shape changes
versus v2: the builds endpoint returns a top-level array ordered newest-first
(v2 was an object with a builds array, oldest-first), and each build carries a
ready-made download url under downloads."server:default".url, so the jar URL no
longer needs to be templated. Verified against the live API: the latest-build
path and an explicit-build lookup both resolve to a valid server jar.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@okafke

okafke commented Jul 13, 2026

Copy link
Copy Markdown
Member

Thanks, will base on this and fix it in a sec. With the animosity many people have towards AI, I would prefer to not have Claude as a contributor in the headlesshq repositories.

Continued in #429

@okafke
okafke changed the base branch from main to paper-fill-api July 13, 2026 15:28
@okafke
okafke merged commit 6bbd80c into headlesshq:paper-fill-api Jul 13, 2026
36 of 56 checks passed
@ChipWolf
ChipWolf deleted the fix/papermc-v3-fill-api branch July 13, 2026 18:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants