Troubleshooting mod development
This page is about building and running Poly Mods. If you play with mods, see If something goes wrong in the install guide and the Player FAQ.
Mod development
| Symptom | Cause and fix |
|---|---|
Plugin dev.polymodloader.mod not found, or a dev.polymodloader:… artifact cannot be resolved | Gradle could not reach the website's Maven repository https://www.polymc.net/maven/, or the version in build.gradle.kts is not published there. Check your internet connection and the version. Once everything is in the Gradle cache, you can build offline with --offline. With -PpolyLocalSdk, Gradle looks in Maven Local first. See Get the mod template. |
Poly Mod Loader launch stopped in phase … | Look up the error code in the log (POLY-…) in the error code table. An entrypoint exception is POLY-ENTRYPOINT-003. |
POLY-CONTENT-002 | You declared content after the entrypoint finished (for example, inside an event). Move the declaration into the entrypoint. |
POLY-METADATA-… | poly.mod.json is invalid. build tells you which field. |
POLY-DEPENDENCY-007 | No entry in the minecraft list of poly.mod.json matches the game version that is running. Fix the list (Write the version) or run with a matching version. |
Minecraft … is not supported by this Poly Mod Loader build; supported: [...] | You set polyMinecraft (gradle.properties or -PpolyMinecraft) to a version the Poly Mod Loader you use does not support. Pick one from the supported list in the message. |
runServer fails with The Minecraft dedicated server requires accepting the Minecraft EULA | run/server/eula.txt does not contain eula=true. Poly Mod Loader does not accept for you. Read the EULA yourself, and if you agree, create that file yourself. |
| Texture is a purple and black checkerboard | The mod ID or folder name in the model or texture path is wrong. checkPolyResources in build reports missing models and textures and missing namespaces, file by file (Mod Development Tools). |
POLY-RESOURCE-004 to 009 (during build) | A problem with a resource file name, JSON, a reference, a translation, or a polyResources declaration. The message tells you the path to fix. |
| Breaking a block drops nothing | data/<mod>/loot_table/blocks/<block>.json is missing. |
No data fixer registered for <mod mob> | You can ignore it. The game logs this at startup for mod entities it has no data conversion for. |
| Authentication error logs for Realms or online servers | Expected, because development runs use an offline account. |
Recover the run environment
| Symptom | Where to look | What to do |
|---|---|---|
Poly Mod Loader launch stopped in phase … | The error code in the console and in run/<side>/logs/latest.log | Look it up in the error code table, then fix or remove the mod concerned. |
| A mod is not loaded | blockedFiles and foreignMods in run/<side>/.poly/startup-report.json | Check the per-feature POLY-COMPAT-* reason. |
A Fabric mod fails when a game class loads (POLY-COMPAT-133) | The log message names the class, the mixin, and its mod | Remove that mod or try a newer version of it. |
| Something odd with transforms | .poly/transformation-report.json, -Dpoly.transformDumpDir=<dir> | If you suspect the cache, run with -Dpoly.transformCacheDir=none and compare. Corrupted cache entries are discarded automatically. |
| Download hash mismatch | ~/.gradle/caches/poly-minecraft | Delete the file and run again. |
| You suspect world corruption | <world>/poly/mods.properties, the game's backups/ | Poly Mod Loader backs up a world before loading it if mods were removed or versions changed. See Operations. Still, back up important worlds yourself before you run. |
Startup errors (POLY-BOOTSTRAP)
These are errors that occur while Poly Mod Loader prepares the launch configuration, the game jar, the version adapter, and the game layer. The list of codes is in Error codes.
| Code | Cause shown in the log | What to do |
|---|---|---|
POLY-BOOTSTRAP-001 | The game jar has no version.json, or the jar cannot be read | Check that poly.gameJar points to a Minecraft game jar. |
POLY-BOOTSTRAP-002 | no version adapter for Minecraft …: no version adapter handles the game jar's version. The message lists the versions this Poly Mod Loader supports | Run a game of a supported version. In a mod project, pick it with polyMinecraft. |
POLY-BOOTSTRAP-003 | invalid launch configuration: …: a required system property (poly.launchTarget, poly.gameJar) is missing, the poly.launchTarget value is wrong, or the poly.gameJar file does not exist. The launcher exits with code 2 | Check the launcher system properties below. The Gradle run tasks set these values automatically. |
POLY-BOOTSTRAP-004 | A game layer class is outside the dev.polymodloader.game.layer package, is not on Poly Mod Loader's classpath, or is not in the jar | The version adapter brings in the game layer jar as a runtime dependency. If you built the classpath yourself, check that the game layer jar for that version (poly-game-v26_2) is present. |
POLY-BOOTSTRAP-005 | An exception occurred while creating or starting the game layer | Check the cause exception that follows in the log. |
Launcher system properties
The Poly Mod Loader launcher (dev.polymodloader.bootstrap.PolyLauncherMain) takes its settings as Java system properties (-D…). The Gradle run tasks (runClient, gameTests, and so on) set the values below automatically, so you only need to care about them when you start the launcher yourself.
| Property | Meaning | Default | Value the Gradle run tasks set |
|---|---|---|---|
poly.launchTarget | One of client, dedicated_server, game_test_server | None (required) | Differs by task |
poly.gameJar | The Minecraft game jar | None (required) | The downloaded and verified jar |
poly.modsDir | Mods folder | mods | <run directory>/mods |
poly.devModJars | More mod jars to load, separated by the path separator (; on Windows, : elsewhere) | None | The mod project's jar |
poly.reportDir | Poly Mod Loader report directory | .poly | Default |
poly.transformCacheDir | Transform cache directory. none turns the cache off | <poly.reportDir>/transform-cache | build/poly/transform-cache |
poly.transformCacheMaxMegabytes | Upper limit for the transform cache size (MiB). When exceeded, the least recently used entries are deleted first | 256 | Default |
poly.transformDumpDir | Directory to write the classes before and after transformation | None (nothing written) | Not set |
Relative paths are relative to the JVM working directory. The Gradle run tasks use the run directory (run/client and so on) as the working directory. The launcher passes the remaining program arguments to Minecraft unchanged.
Diagnostic reports
On every run, Poly Mod Loader writes reports to .poly/ in the game directory.
| File | Contents |
|---|---|
.poly/startup-report.json | Loaded mods, blocked files, active systems, and the transform plan |
.poly/transformation-report.json | Classes actually transformed, hashes before and after, and whether the cache was used |
At startup, Poly Mod Loader writes a [Poly Mod Loader] Phase … log line for each phase. The order is BOOTSTRAP (check the game jar) → DISCOVERY (find and classify mods) → METADATA_VALIDATION → DEPENDENCY_RESOLUTION (dependency and link checks) → CONFLICT_RESOLUTION (system replacement) → TRANSFORMATION_PLANNING → SYSTEM_REGISTRATION → LIFECYCLE_INITIALIZATION (Poly Mod entrypoints) → GAME_LAUNCH. Fabric mods follow Fabric Loader's timing instead: preLaunch runs before the game starts, and main, client and server run later, inside the game's own startup. If startup stops, the phase name in launch stopped in phase … tells you where it stopped.
Report a bug
If this page does not help, report the bug on the website. Include the error code (POLY-…) and a link to logs/latest.log or the crash report; the two reports above help too. The maintainers read every report.