> ## Documentation Index
> Fetch the complete documentation index at: https://docs.purpify.host/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot Java mod-loader mismatches

> Fix Forge, NeoForge, Fabric, or Quilt loader and version mismatches on a Purpify Minecraft Java server.

The server, every server-required mod, and each joining player's client must use a compatible Minecraft version and mod loader. Forge, NeoForge, Fabric, and Quilt mods are not interchangeable unless the mod author explicitly provides compatibility.

## Record the required combination

Write down the exact:

* Minecraft version
* Loader family: Forge, NeoForge, Fabric, or Quilt
* Loader version
* Mod or modpack release
* Dependency versions
* Java runtime required by that Minecraft and loader release

Do not compare only the mod name. Two files with the same name may target different loaders or Minecraft versions.

## Read the first loader error

| Error pattern                                                       | What it usually means                                                          |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| Mod requires a different Minecraft version                          | The mod build and server version do not match.                                 |
| Mod requires `fabricloader`, `forge`, `neoforge`, or `quilt_loader` | The wrong loader is installed or its version is outside the required range.    |
| Missing mandatory dependency                                        | A library or API mod is absent.                                                |
| Mod is for a newer or older loader version                          | The loader must be updated or the mod must be changed to a compatible release. |
| Client reports an incompatible mod list                             | Client and server mod sets or versions differ.                                 |
| Error references client-only rendering or environment code          | A client-only mod was uploaded to the server.                                  |

## Correct the mismatch

<Steps>
  <Step title="Stop and back up">
    Stop the server and create a [backup](/server/backups).
  </Step>

  <Step title="Choose one target combination">
    Use the modpack manifest or mod author's requirements to choose the Minecraft version, loader family, and loader version.
  </Step>

  <Step title="Install the matching server software">
    Select the compatible version in the Purpify installer. Do not mix loader families in the same `/mods` folder.
  </Step>

  <Step title="Replace incompatible mods">
    Upload releases for the selected loader and Minecraft version, including required API or library mods.
  </Step>

  <Step title="Match player clients">
    Install the same required mod and loader versions on player clients. Keep optional client-only mods off the server.
  </Step>

  <Step title="Start and test">
    Start once and read the first remaining error. Join only after the console reports a completed startup.
  </Step>
</Steps>

<Columns cols={2}>
  <Card title="Install mods and modpacks" icon="cubes-stacked" href="/java/mods">
    Review manual and installer-based mod setup.
  </Card>

  <Card title="Client-only mod crashes" icon="display" href="/troubleshooting/client-side-mods">
    Remove rendering and interface mods from the dedicated server.
  </Card>
</Columns>