Skip to content

Troubleshooting

natan307 edited this page Nov 16, 2026 · 1 revision

Troubleshooting

First run /packloader diag and read plugins/PackLoader/diag.txt. It shows the pack URL, whether this machine can reach it, and your config (secrets hidden).

The first thing to check: the port

Most problems are the HTTP port. Make sure that:

  1. http.port is an extra port and not the Minecraft port.
  2. That port is open for TCP (panel allocation, firewall, router).
  3. http.public-host is your real domain or IP.
  4. You restarted the server after changing the port.
  5. /packloader url opens in a browser on another network.

The upload link opens a blank page (about:blank)

A blank tab means the browser never loaded the address.

  • Clicking a link in the Minecraft chat often fails on phones/launchers. Copy the link and paste it into the browser.
  • The link has the wrong host: set http.public-host and run /packloader reload, then /packloader upload again.
  • The port is closed or not an extra port (see above).
  • The token expired (default 15 minutes). Run /packloader upload again.

No upload page needed: you can also copy a .zip straight into plugins/PackLoader/packs/ and run /packloader reload.

The player gets no prompt

  • send.on-join is false, or the pack was still being built when the player joined. Run /packloader send.
  • The web server did not start. Look for Could not start the pack web server in the log.

"Failed to download" / the pack is never applied

  1. Open the pack URL (/packloader url) in a browser on a different network, for example mobile data.
  2. If it does not load: the port is closed, http.public-host is wrong, or your host does not allow extra ports. Fix the firewall/forwarding, or use a CDN.
  3. If diag.txt says the self-test passed but players still fail, the problem is outside the server (firewall, ISP, NAT).

Web server does not start

Message Cause
Address already in use Another program uses the port (often the Minecraft port). Use an extra port and restart
NoClassDefFoundError com/sun/net/httpserver The Java runtime has no jdk.httpserver module. Use a full JDK/JRE
Nothing listens from outside http.bind-address is not 0.0.0.0, or the host firewall blocks it

Items look wrong

Symptom Cause
Shows as plain paper Player did not accept the pack, the server/client is older than 1.21.4, or the client failed to load the pack
Purple-black cube Wrong texture/model path, or a texture referenced by the model is missing. Read the console warnings after a build
Wrong size/rotation in hand or GUI Adjust the display section of the model JSON

Blocks

Symptom Cause
Cannot place Adventure/Spectator mode, a protection plugin cancelled it, or a living entity stands there
Model too small / odd rotation Change block.transform (try FIXED or HEAD) or block.scale
Leftover model after /fill Blocks removed without events. Re-enter the chunk or remove the entity

GUIs

Symptom Cause
No background Server is Spigot (no Adventure), pack not accepted, or the background texture path is wrong (see console)
Background shifted Use offset_x / offset_y
Items hidden by the background Make the slot areas transparent in the PNG
Players cannot open it /packloader gui needs packloader.admin; see Custom GUIs

Pack build warnings

  • Invalid resource path: a file under assets/ has uppercase letters or illegal characters. Rename it.
  • Skipping invalid zip: the file in packs/ is not a valid zip.
  • Could not merge: a JSON file has a syntax error; the later pack wins instead of merging.
  • pack is larger than 250 MiB: clients refuse it. Reduce texture sizes or remove unused files.

Collecting information for a bug report

  1. Run /packloader diag.
  2. Copy the startup log from the line Loaded ... custom item(s) onward, plus any stack trace.
  3. State the server software and exact version, and the client version.
  4. Open an issue and attach both.

Clone this wiki locally