FAQ for mod developers

Questions from players are in the Player FAQ.

Compatibility and versions

Can I use Forge, Fabric, NeoForge, or Quilt mods?

Mostly yes, for all four. Fabric and Quilt mods can be mixed in one game with Forge mods or with NeoForge mods, except those whose mixins do not fit that loader's patches, (Run Fabric and Forge mods together). Forge and NeoForge mods do not run in the same game yet. On Minecraft 26.3, mixing loaders works since 1.2.5 (popular-mod sets, headless, 2026-10-28); 1.2.4 stopped such games at start.

Mod	Status
Forge mods	Verified Poly Mod Loader runs Forge and FML themselves. On 26.1 and 26.2, popular Forge mods play a saved world on the client, save it and quit (40 on 26.2), and start a real dedicated server. The only mods left out are ones Forge refuses too. Next to Fabric and Quilt mods it is Partial: on 26.2 no Fabric API module is left out, but Architectury, Balm and Lithium are (POLY-COMPAT-224), with the mods that need them; 88 foreign mods load and 78 are left out (2026-10-28, 1.2.5). Features were not checked mod by mod
Fabric mods, including mods that use Mixin, MixinExtras, nested jars, or class tweakers	Verified On 26.1 and 26.2, popular Fabric mods play a saved world on the client, save it and quit (138 real mods on 26.2, plus 2 test mods), and start a real dedicated server together (100 on 26.2). Features were not checked mod by mod
Fabric mods that use Fabric Loader's internal classes (net.fabricmc.loader.impl)	Partial the parts real mods use are provided (FabricLauncherBase.getLauncher(), FabricLoaderImpl.getGameProvider()); a mod that needs the rest is left out with a diagnosis (POLY-COMPAT-111)
NeoForge mods	Verified Poly Mod Loader runs NeoForge and its loader FML themselves; NeoForge's files are downloaded on the first start. On 26.1, 26.1.2 and 26.2, popular NeoForge mods play a saved world on the client, save it and quit (54 on 26.2), and start a real dedicated server. The only mods left out are ones NeoForge cannot run either. Next to Fabric and Quilt mods it is Partial: a Fabric or Quilt mod whose mixins do not fit NeoForge's patches is not loaded (POLY-COMPAT-224), on 26.2 10 Fabric API modules and the Fabric mods that need them; with the rest, 40 foreign mods and 40 NeoForge mods create and save a world on the 26.2 game test server (2026-10-27, 1.2.4). Not with Forge mods: then Forge runs and the NeoForge mods are left out (POLY-COMPAT-221). Features were not checked mod by mod
Quilt mods	Verified On 26.1, 26.1.2 and 26.2, checked with every Quilt-only build on Modrinth for the version on the client, the game test server and the dedicated server, and compared with real Quilt Loader: the only mods left out are ones Quilt Loader cannot load or run either. quilt.mod.json is read with Quilt Loader's meaning, and the Quilt Loader API is provided. Quilt Standard Libraries (QSL) has no release for 26.x, so a mod that needs it is left out (POLY-COMPAT-114 with 308). A Quilt mod that also ships fabric.mod.json runs as a Fabric mod (310). Next to Forge or NeoForge mods, the same limit as Fabric mods applies. Features were not checked mod by mod

A blocked mod is not loaded. The reason goes to the log and to .poly/startup-report.json, and the other mods still load. See Compatibility. To use Fabric and Forge mods in one game, see Run Fabric and Forge mods together.

Do I have to rebuild my mod for every Minecraft version?

Not if it uses only the Native API. If you write "26.*" or ">=26.2 <27" in the minecraft field of poly.mod.json, the mod runs on a new version without a rebuild once Poly Mod Loader supports that version. The game layer for that version must implement every API the mod uses.

A mod that depends on game code of a specific version, such as one with transform rules (transforms), must name the exact version. That mod loads only on the versions it lists. If the version does not match, launch stops with POLY-DEPENDENCY-007.

What do I put in "minecraft" in poly.mod.json?

The mod template uses "26.*". If the mod uses only the Native API, write a wildcard or a range. If it depends on game code of a specific version, write the exact version, such as "26.2". A wrong format gives POLY-METADATA-009. poly.mod.json describes each format.

How do I run my mod on a different Minecraft version?

Set polyMinecraft=<version> in the mod project's gradle.properties, or add -PpolyMinecraft=<version> to the command. Only versions your Poly Mod Loader supports work: 26.1, 26.1.1, 26.1.2, 26.2, 26.3 for Poly Mod Loader 1.4.0. See Running tests.

Why are there no mappings?

They are not needed. Since Minecraft 26.1, Mojang ships Java Edition unobfuscated, with its original names. Poly Mod Loader's transform rules name the target classes and methods directly, using Mojang's original names and JVM descriptors. On 26.x, Fabric and NeoForge mods use the same names.

A mod that uses only the Native API uses no Minecraft names. The Native API has no Minecraft types, and Poly Mod Loader's game layer provides the implementation for each game version.

Installation and distribution

Is there an installer or a public Maven repository?

Yes.

• Players install Poly Mod Loader with the installer from the download page. It adds a Poly Mod Loader profile to the Minecraft Launcher. See Install.
• Mod developers do not need the Poly Mod Loader source. The website's Maven repository https://www.plexusmc.net/maven/ has the mod template, the dev.polymodloader.mod plugin, and Poly Mod Loader itself, without source code. See Get the mod template.

What is still missing is listed in Not yet available.

Where do I put the mod jar I built?

Put the jar from build/libs/ in run/client/mods/ of the Poly Mod Loader run environment (run/server/mods/ for the server). If a mod uses the same content on the server and the client, both sides need the same version of the jar. See Build, Run, Deploy.

Does Poly Mod Loader accept the Minecraft EULA?

No. Poly Mod Loader does not accept it on your behalf.

• If run/server/eula.txt does not contain eula=true, runServer fails before it starts the game and shows a guidance message. Read the EULA yourself, and if you agree, create that file yourself.
• serverBootSmokeTest starts the server in an empty directory every time, so the server stops at the EULA check. The task verifies only the log up to that point.
• worldCreateSaveTest and gameTests use the Mojang game test server, so they do not need an EULA file.

See Running tests.

I get an authentication error on online servers or Realms.

This is expected. Development runs use an offline account (PolyDev). Single player works, but online servers and Realms give an authentication error. See Requirements.

API and errors

Does the API change between versions?

It can. Every public API in Poly Mod Loader 1.4.0 has the PREVIEW level, and the 0.1 line has no STABLE API with a compatibility promise. Changes are listed in the Changelog, and the levels are explained in API stability.

Where do error codes come from?

Poly Mod Loader reports problems as POLY-area-number codes.

• Problems in poly.mod.json (POLY-METADATA-*) are reported first by the validatePolyModJson task in build. The same checker validates the file again at launch.
• Problems at run time appear in the console and in run/<side>/logs/latest.log. If startup stops, the code follows Poly Mod Loader launch stopped in phase ….
• The reason a mod was not loaded is also written to .poly/startup-report.json.

The meaning of each code and what to do are in Error codes. Fixes by symptom are in Troubleshooting. The meaning of an existing code never changes. A new problem gets a new number.