Repository navigation
Troubleshooting
natan307 edited this page Nov 16, 2026
·
1 revision
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).
Most problems are the HTTP port. Make sure that:
-
http.portis an extra port and not the Minecraft port. - That port is open for TCP (panel allocation, firewall, router).
-
http.public-hostis your real domain or IP. - You restarted the server after changing the port.
-
/packloader urlopens in a browser on another network.
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-hostand run/packloader reload, then/packloader uploadagain. - The port is closed or not an extra port (see above).
- The token expired (default 15 minutes). Run
/packloader uploadagain.
No upload page needed: you can also copy a .zip straight into plugins/PackLoader/packs/ and run /packloader reload.
-
send.on-joinisfalse, 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 serverin the log.
- Open the pack URL (
/packloader url) in a browser on a different network, for example mobile data. - If it does not load: the port is closed,
http.public-hostis wrong, or your host does not allow extra ports. Fix the firewall/forwarding, or use a CDN. - If
diag.txtsays the self-test passed but players still fail, the problem is outside the server (firewall, ISP, NAT).
| 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 |
| 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 |
| 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 |
| 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
|
-
Invalid resource path: a file underassets/has uppercase letters or illegal characters. Rename it. -
Skipping invalid zip: the file inpacks/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.
- Run
/packloader diag. - Copy the startup log from the line
Loaded ... custom item(s)onward, plus any stack trace. - State the server software and exact version, and the client version.
- Open an issue and attach both.
PackLoader by Natan/Ezra - All Rights Reserved - github.com/natan307
PackLoader
Features
Reference