Skip to main content

Resource Pack Manager Troubleshooting

This page only covers behavior that is currently confirmed in the ResourcePackManager codebase.

The single most useful first step for any RSPM issue is:

/rspm status

It prints version, deploy mode (standalone vs network-backend), masked network key, Java + Bedrock pack state, the active delivery path with URL, the resolved external host + auto-detected public IP, all relevant config flags, a proxy-deployment reminder (the network proxy jar is the same ResourcePackManager.jar), and Floodgate / Geyser-Spigot detection. The same command exists when the jar runs on a proxy and prints proxy-side equivalents (backend list, per-backend fetch outcomes, merged-pack state).

Players are not receiving the resource pack​

Check these first:

  • autoHost must be enabled if you want ResourcePackManager to push a URL automatically
  • the merged pack must exist and at least one delivery path (self-host or remote) must have succeeded
  • players only receive the pack on join, or via the first-upload broadcast that fires the moment hosting becomes ready

If needed:

  1. Run /rspm status and look at the "Hosting" section. Active delivery shows whether self-host, remote, or neither is currently in use.
  2. If "active delivery: not yet ready" — the mix or upload is still in progress. The plugin loud-banners this in the console when a player joins too early and will auto-send the pack the moment delivery is ready.
  3. If "active delivery: none — hosting disabled or failed" — autoHost is off, or self-host probes and remote upload both failed. See "Self-host sanity checks failed" and "Auto-hosting cannot reach the remote server" below.
  4. Run /rspm reload, watch console for upload / self-host probe results, then rejoin with a test player.

If you are self-hosting through your own external pipeline (autoHost: false), RSPM does not push your custom URL for you. In that setup you still need your own server-side pack delivery flow.

ItemsAdder is installed, but its content is missing from the final pack​

This usually means ItemsAdder is still configured in a way that prevents ResourcePackManager from reading or hosting its output.

Use:

/rspm itemsadder configure

That command currently:

  • enables resource-pack.hosting.no-host.enabled
  • disables protection_1, protection_2, and protection_3
  • sets resource-pack.zip.compress-json-files: false
  • runs /iareload, then /iazip
  • reloads ResourcePackManager about 15 seconds later

If the command tells you ItemsAdder is already hosting its own pack, disable ItemsAdder hosting manually first and run the command again.

The merged pack is invalid or fails to upload​

ResourcePackManager's auto-host integration explicitly handles these server-side error types:

  • missing required files
  • file too large
  • invalid file format
  • missing session
  • remote server unavailable

If you hit one of these:

  1. Run /rspm reload to rebuild the pack.
  2. Check whether one of the source packs is malformed, encrypted, or otherwise unreadable.
  3. Check whether the final merged pack still contains a valid pack.mcmeta and pack.png at the root.

The plugin skips packs it cannot extract cleanly and logs warnings in console when that happens.

On a SESSION_NOT_FOUND error from the remote auto-host, RSPM clears its session UUID and re-initializes on the next keep-alive tick — no manual intervention required.

One plugin's assets are overriding another plugin's assets​

This is controlled by priorityOrder in:

plugins/ResourcePackManager/config.yml

Higher entries win over lower entries.

For non-mergeable files, ResourcePackManager replaces the lower-priority file. For mergeable JSON files, it merges content instead. The currently mergeable JSON categories are:

  • sounds.json
  • language files
  • vanilla item model JSON in minecraft/models/item (non-recursive merge: only the overrides array is combined across packs, the rest of the file follows highest-priority-wins)
  • atlas files
  • font files
  • 1.21.4+ item model definitions in items/ (format-aware merge that respects predicate-tree structure)

pack.mcmeta is also merged specially: the highest pack_format wins, supported_formats ranges are widened (integer, two-int array, and {min_inclusive, max_inclusive} object forms are all supported), overlay entries are combined, and non-standard top-level keys are preserved. Overlay entries are normalized for 1.21.9+ compatibility by adding min_format/max_format fields when missing. Base atlas sources are also merged into overlay atlas files to prevent overlays from shadowing base entries.

If you need to inspect what happened during the last merge, check:

plugins/ResourcePackManager/collision_log.txt

GUI text or font-based elements look wrong​

Font files are one of the JSON categories ResourcePackManager merges, but that does not guarantee two different font systems will behave well together in Minecraft.

If a font-driven menu or HUD looks wrong:

  1. Change priorityOrder so the pack you want to win is higher.
  2. Run /rspm reload.
  3. Check collision_log.txt to confirm collisions happened where you expected.

Resource pack changes are not showing up immediately​

ResourcePackManager has a watchdog for supported pack sources.

It waits until a changed pack remains unchanged for 3 seconds, then once all watched packs are stable the remix happens immediately.

If you are actively regenerating another plugin's pack, give it a few seconds after file writes stop. If in doubt, run /rspm reload after the upstream plugin finishes.

Self-host sanity checks failed; falling back to remote hosting​

This message is normal behaviour when preferSelfHost: true (the default) and one of the three self-host sanity checks failed:

  1. Layer 1 (heuristic) — the resolved external host is RFC1918 / loopback / link-local. Either set selfHostExternalHost to your real public hostname, or ensure the plugin can reach api.ipify.org / checkip.amazonaws.com.
  2. Layer 2 (localhost self-probe) — a HEAD request to http://127.0.0.1:<port>/rspm.zip did not return 200 with a non-empty body. Catches port-bind collisions or missing pack files.
  3. Layer 3 (external reachability probe) — magmaguy.com tried to fetch your announced URL and couldn't reach it. Most commonly: the HTTP port isn't forwarded at the router / firewall. The probe URL and reason are logged.

Fixes (in order of preference): open the HTTP port at your firewall + router, set selfHostExternalHost to a routable hostname, or set preferSelfHost: false to skip self-host entirely.

When the magmaguy.com probe is itself unreachable (RSPM can't talk to it to ask), self-host is kept rather than failed — the rationale being that the fallback path needs magmaguy.com too, so refusing to commit on inability-to-probe would be paradoxical.

See Self-hosting for the full decision tree.

Auto-hosting cannot reach the remote server​

ResourcePackManager's built-in remote host talks to:

https://magmaguy.com/rsp/

If that connection fails, the plugin logs communication warnings and cannot use the remote fallback until it reconnects successfully.

Your options are:

  1. fix the server's outbound HTTPS connectivity
  2. wait for the remote service to become reachable again
  3. disable autoHost and host the generated zip yourself
  4. open your HTTP port and keep preferSelfHost: true so RSPM uses self-hosting without needing magmaguy.com at all (in this scenario, also set selfHostExternalHost to your public hostname so the Layer 3 external probe is unnecessary — RSPM keeps self-host on probe-IOException)

I want to self-host the merged pack through my own web server​

The code-supported setup is:

  1. Set autoHost: false.
  2. Set resourcePackRerouting if you want ResourcePackManager to write an extra copy into an existing folder.
  3. Host ResourcePackManager_RSP.zip yourself.

resourcePackRerouting is resolved relative to the plugins directory, and the target folder must already exist.

If instead you want to use RSPM's built-in self-host HTTP server (different thing — same JVM as the plugin), see Self-hosting.

I need to inspect what remote data is stored for this server​

Use:

/rspm data_compliance_request

If there is an active remote hosting session, ResourcePackManager downloads the response into:

plugins/ResourcePackManager/data_compliance

If there is no remote session (e.g. you're using self-host), the command reports that there is no remote data to request.

Bedrock pack is not being generated​

bedrockConversionEnabled defaults to true, so it should run automatically. Run /rspm status first — the Bedrock Pack section will tell you why the pack isn't on disk:

  • "No Bedrock target detected" — no local Geyser-Spigot, no local Floodgate, and not in network mode. Conversion is intentionally skipped. Install Floodgate (for proxy setups) or Geyser-Spigot (for standalone setups) and /rspm reload.
  • "Network mode is active so this backend SHOULD produce a Bedrock pack. The file is missing" — usually the first mix cycle hasn't completed yet (wait ~30s after boot), or the scanner found zero items definitions in the merged pack, or conversion threw. Search the console for [BedrockConverter] warnings or for Generic scanner: discovered 0 items definition files.

If Geyser auto-detection fails:

  1. Set bedrockGeyserFolder in config.yml to the path of your Geyser data folder (e.g. Geyser-Spigot).
  2. The path can be absolute or relative to the plugins directory.

The converter auto-detects Geyser in plugins/Geyser-Spigot/, any plugins/Geyser-*/ variant, or config/Geyser-*/ for Fabric/NeoForge setups.

For per-item / per-bone log output, set bedrockConverterDebug: true and reload.

Bedrock players see held items in the wrong position​

This is a tuning issue, not a conversion bug. Open plugins/ResourcePackManager/bedrock_display_offsets.yml and adjust the relevant axis. First-person and third-person are independent — tuning one does not affect the other. The Bedrock client live-reloads attachable JSON without a relaunch, so iteration is fast. See Bedrock conversion for the full list of knobs and what each one controls.

Custom armor textures are missing on Bedrock players​

Custom armor renders on Bedrock by combining the vanilla armor geometry with the Java texture as a visible layer. For this to work, the source plugin's pack must define an equipment file under assets/<namespace>/equipment/<material>.json alongside the items definition. If the conversion log shows the item but no armor texture appears in-game, verify that file exists in the merged pack.

Proxy: "Floodgate key.pem missing" on proxy boot​

The proxy plugin couldn't find plugins/floodgate/key.pem on the proxy host and idled. RSPM derives the network identity from that file, so without it the proxy can't link to any backend. Fix:

  1. Install Floodgate on the proxy. It's required for Bedrock players to reach the proxy anyway, so this is something you need regardless of RSPM.
  2. Make sure plugins/floodgate/key.pem on the proxy is byte-for-byte identical to the same file on every backend. Copy one canonical key.pem to every component (other backends + the proxy) and restart everything. Floodgate already requires this for Bedrock auth, so if Bedrock players currently work across your network, this is already done.

Proxy: "no merged pack" after several poll cycles​

After ~20 seconds of empty poll cycles (4 cycles × 5 s default interval) on the proxy, RSPM logs a one-shot diagnostic banner listing every backend it polled, the HTTP URL it tried, and the outcome (200 / 304 / 404 / CONNECT_FAILED / etc.). The banner explains the most common fixes:

  • CONNECT_FAILED on every backend → the proxy can't reach the backend's HTTP port. Check that the address in velocity.toml / config.yml is one the proxy can actually reach (not e.g. a Docker-internal name that doesn't resolve from the proxy's network), and that the backend's announced HTTP port is open between proxy and backend. The banner prints the exact URL it tried; before a backend has announced its port the proxy falls back to mcPort + network-http-offset-v2, so an early CONNECT_FAILED can also mean that fallback port isn't reachable yet.
  • NOT_FOUND_404 on every backend → backends are up but not producing a Bedrock pack. Run /rspm status on each backend; the Bedrock Pack diagnostic block will tell you why.

The banner fires once per stuck period and an "NetworkSync: recovered" line is logged when at least one backend starts returning content again. See Proxy networks for more.

Proxy: Bedrock players see no models on first proxy boot​

Geyser registers its custom-item table at proxy startup only. If the proxy started before any backend produced a Bedrock pack, Geyser is running with an empty mappings table and stays that way for the rest of the session.

The fix is to restart the proxy after the backend has logged Wrote merged Geyser mappings: N entries. RSPM pre-deploys the previous run's mappings on proxy boot so this only ever bites on a brand-new install — subsequent boots have something ready before Geyser scans.

Backend: "Backend HTTP server failed to bind on port X"​

In network mode, the backend exposes its Bedrock outputs through a small HTTP server. If the port is in use or unavailable, you'll see a multi-line [ERROR] block in the console. Fixes:

  • Set selfHostPort to a different positive value in config.yml.
  • Or change networkHttpOffset-v2 to push the auto-derived port away from the collision (e.g. RCON on mcPort + 1? set it to 2 or 3). You do not need to update the proxy to match: once the backend binds successfully it announces its actual HTTP port to the proxy automatically, so the proxy's own network-http-offset-v2 only matters as a pre-announcement guess.

While the backend HTTP server is down, this backend's Bedrock pack won't reach the proxy via direct fetch. The magmaguy.com relay fallback still works (the backend pushes its files to the relay and the proxy fetches them through there).

Cleaning up an outdated v1 config​

Operators upgrading from RSPM v1 may have a dead networkHttpOffset (no -v2) key in their config.yml. RSPM v2 intentionally does not read the old key — you get the v2 default (1) written to config on next boot automatically. The dead v1 key sits in your config as a harmless artifact until you clean it up by hand.