---
title: "How to Run a Custom Server JAR on a Minecraft Server"
description: "Run Minecraft server software that isn't in the Framework dropdown: uploading your own jar, the Server Jar File variable, and the reinstall that deletes it."
url: "https://www.gameserverkings.com/knowledge-base/minecraft/install-a-custom-jar/"
category: "Minecraft"
category_url: "https://www.gameserverkings.com/knowledge-base/minecraft/"
published: "2026-08-19T10:04:51.588Z"
updated: "2026-08-19T10:49:54.856Z"
source_format: "markdown"
site: "GameServerKings"
---

# How to Run a Custom Server JAR on a Minecraft Server

The **Framework** dropdown on the Startup tab offers seven choices, and for the overwhelming majority of servers one of them is the right answer. But the Minecraft ecosystem is bigger than seven: Paper forks appear and disappear, Sponge exists, some people compile their own builds, and occasionally a community pack ships a jar you cannot get any other way. This guide covers running a server jar we do not install for you — how the launch command finds it, what to change, and the one action that silently deletes it.

Choosing between the frameworks we *do* install is a different question, answered in [Minecraft Server Software Compared](/knowledge-base/minecraft/choosing-server-software/).

## What the Framework Dropdown Actually Does

Two separate things happen on a Minecraft server, and it helps enormously to keep them apart.

**At install time**, an installer script runs. It reads the Framework, Minecraft Version and Build Number variables, downloads (or, for Spigot, compiles) the matching jar from that project's official source, and writes it into your server root under the name in the **Server Jar File** variable. Vanilla comes from Mojang's version manifest, Paper from `fill.papermc.io`, Purpur from `api.purpurmc.org`, Fabric from `meta.fabricmc.net`, Forge from the Forge promotions feed, and NeoForge from the NeoForged Maven.

**At start time**, none of that matters. The launch command is fixed, and it looks like this:

```bash title="The launch command on a GSK Minecraft (Java) server"
java -Xms128M -XX:+IgnoreUnrecognizedVMOptions -XX:MaxRAMPercentage=95.0 \
  -Dterminal.jline=false -Dterminal.ansi=true \
  -jar server.jar \
  $EXTRA_FLAGS
```

The only part of that line the Framework variable touches at start time is nothing at all. The jar that gets launched is whatever file is named in **Server Jar File**, which defaults to `server.jar`. If that file is a Paper jar, you have a Paper server. If it is a jar you uploaded yourself, you have that.

That is the whole trick. There is no "custom" entry in the dropdown because you do not need one.

![The Startup tab of a GSK Minecraft (Java) server: the resolved launch command ends in -jar leaf-26.2-83.jar while the Framework variable is still set to PAPER, and the Server Jar File field holds the uploaded filename](<https://cdn.gskinternal.com/articles/images/minecraft-startup-server-jar-file.png>)

> [!IMPORTANT] One exception: `unix_args.txt`
> The launcher checks for a file called `unix_args.txt` in the server root first. If it exists, the server is launched from that arguments file **instead** of `-jar <your jar>`, and your jar is ignored entirely. This is how modern Forge and NeoForge boot. If you are moving to a custom jar from a Forge or NeoForge install, delete `unix_args.txt` or nothing you do to the Server Jar File variable will have any effect.

## Installing Your Own Jar

1. **Get the jar from the project's own download page.** Not a reupload, not a Discord attachment, not a video description link. A Minecraft server jar you cannot trace to an official source is a jar you are running as root on your own machine.

2. **Note the Minecraft version and the Java version it needs.** Both matter and both are checkable — see [Updating Your Minecraft Server](/knowledge-base/minecraft/updating-your-server-version/).

3. **Stop the server** from the Console tab and wait for the process to exit.

4. **Upload the jar to the server root** — the same directory as `server.properties` and `eula.txt`. Use the **File Manager** for small files, or [SFTP](/knowledge-base/general/how-to-upload-files-via-sftp/) for anything large or over a flaky connection. Do not put it in `plugins/` or `mods/`; the launcher does not search subdirectories.

5. **Set the Server Jar File variable** on the **Startup** tab to the exact filename, character for character. The field accepts letters, digits, dots, dashes and underscores followed by `.jar`, and **nothing else** — a path such as `jars/leaf.jar` is rejected by validation, so move the file rather than trying to type your way around it.

6. **Set the Java version.** The Docker Image selector on the Startup tab offers Java 8, 11, 16, 17, 21, 22 and 25. Match it to what your jar needs — anything targeting Minecraft 26.1 or later needs Java 25.

7. **Check `eula.txt` says `eula=true`.** The EULA file is written by the installer, so a server that has been installed at least once already has it. A jar dropped into a fresh, never-installed directory will stop on first boot asking for it.

8. **Start the server and read the console from the top.** A custom jar tells you what it is in its first few lines.

![The Files tab at /home/container with an uploaded leaf-26.2-83.jar in the server root beside eula.txt, server.properties and server.jar, not inside the plugins folder](<https://cdn.gskinternal.com/articles/images/minecraft-file-manager-custom-jar.png>)

> [!TIP] Keep the default filename
> Naming your jar `server.jar` and leaving the variable alone works fine and removes one thing that can be mistyped. The one reason to use a distinctive name is that it makes the file obvious in the File Manager when you come back in six months.

## The Reinstall Trap

This is the part worth reading twice.

Our installer's first action, before it downloads anything, is to clear out the previous framework's artifacts:

```bash title="What the installer removes before it installs"
rm -f "${JARFILE}" run.sh run.bat user_jvm_args.txt unix_args.txt \
      installer.jar installer.jar.log BuildTools.jar
rm -rf libraries/net/minecraftforge libraries/net/neoforged .fabric
```

`${JARFILE}` is the **Server Jar File** variable. So a reinstall deletes the jar that variable names — including your uploaded one, whatever you called it — and replaces it with a freshly downloaded jar for whichever Framework is selected.

Worlds, `server.properties`, `plugins/`, `mods/` and your configuration all survive a reinstall. Your custom jar does not.

> [!WARNING] After uploading a custom jar, do not reinstall
> "Reinstall Server" in the Settings tab is the normal way to change frameworks or repair a broken install, and on a custom-jar server it is the one button that undoes your work. Keep a copy of the jar off the server so that recovering is a re-upload rather than a hunt. If you do reinstall by accident, nothing is lost except the jar — upload it again and set the variable again.

## What Will and Will Not Run This Way

**Anything that is a runnable server jar will run.** The `java -jar` launcher needs a valid archive with a `Main-Class` in its manifest, and it does not care who built it. In practice that covers:

- **Paper forks not in the dropdown.** Leaf, for example, publishes releases tracking current Minecraft versions — its 26.2 build was released on 18 August 2026. These behave like Paper: `plugins/` works, Paper's `config/` directory works, and everything in [How to install plugins](/knowledge-base/minecraft/java-plugins/) applies unchanged.
- **Sponge.** SpongeVanilla is a standalone server jar implementing the SpongeAPI, with its own plugin format that is not Bukkit's.
- **A specific historical build** of something we do install — a Paper build from before a regression, say — which you can fetch by build number from that project's own API.
- **A jar you compiled yourself**, including Spigot builds produced by BuildTools on your own machine.

**What will not work:**

- **Anything that boots from an arguments file rather than a jar.** Modern Forge and NeoForge do this, which is exactly why the launch command has a `unix_args.txt` branch. A loader that expects its own bespoke start script has nowhere to put it.
- **Bedrock server software.** Nukkit, PowerNukkitX and friends are a different game with a different protocol; they need a Bedrock server, not a Java one. See [Setting up your Bedrock Minecraft server](/knowledge-base/minecraft/bedrock/).
- **A plugin, mod or library jar.** These have no entry point. The console says `no main manifest attribute, in server.jar` and stops — see [Error: Unable to access jarfile](/knowledge-base/minecraft/error-unable-to-access-jar-file/) for that whole family of one-line launcher errors.

> [!CAUTION] Hybrid jars deserve a specific warning
> Mohist, Arclight, Magma and similar projects bolt the Bukkit API onto a modded server so that plugins and mods run together. PaperMC's position, quoted in [Minecraft Server Software Compared](/knowledge-base/minecraft/choosing-server-software/), is that *"any hybrids that attempt to support both mods and plugins are fundamentally flawed and not recommended for use."* You can run one here — the mechanism above does not judge — but the world-corruption and duplication history is real, and the supported way to get both plugins and mods is a [Velocity proxy](/knowledge-base/minecraft/multi-server-networks-with-velocity/) with separate backends.

## When It Does Not Start

Work through these in order; almost everything lands in the first three.

| Console line | Cause | Fix |
|---|---|---|
| `Error: Unable to access jarfile <name>` | The Server Jar File variable and the actual filename disagree, or the jar is in a subfolder | Compare them character for character in the File Manager. Full detail in [Unable to access jarfile](/knowledge-base/minecraft/error-unable-to-access-jar-file/) |
| `Error: Invalid or corrupt jarfile` | The upload truncated | Re-upload. Check the file size in the File Manager — a server jar is tens of megabytes |
| `no main manifest attribute` | It is a plugin or library jar, not a server jar | Get the right download from the project |
| `UnsupportedClassVersionError`, or a message naming a Java version | Wrong Java runtime for the jar | Change the Docker Image on the Startup tab. Class file version 69 means Java 25, 65 means Java 21 |
| Nothing at all, or the old server starts | A leftover `unix_args.txt` is hijacking the launch | Delete it and start again |
| `Missing data pack paper` | The world was created by Paper or Purpur and the new jar does not register that pack | Put `--safeMode` in Extra Flags, start once, stop, clear the field |

Anything past those is a crash rather than a launch failure — [Reading Minecraft Server Logs and Crash Reports](/knowledge-base/minecraft/reading-crash-logs-and-common-errors/) covers how to read one.

## What We Can and Cannot Help With

We will help you get a custom jar launching: filenames, variables, Java images, permissions, the File Manager and SFTP are all ours. We can also apply JVM flags such as [Aikar's set](/knowledge-base/minecraft/allocating-ram-and-jvm-flags/) on request, since those live in the part of the command line customers cannot edit.

We cannot debug the software itself. If a fork crashes on a plugin, or a Sponge plugin misbehaves, that is a question for that project's issue tracker — and the fastest way to find out whether the jar is the problem is to set the Framework back to Paper, reinstall, and see whether the symptom follows.

## FAQ

**Do I have to change the Framework variable when I upload my own jar?**
No, and it is worth understanding why. The Framework variable only affects what an installer *would* download. As long as you do not reinstall, it has no effect on a running server. Leave it wherever it is.

**Will plugins still work?**
That depends on the jar, not on us. A Paper fork keeps the Bukkit API and every plugin you have. A mod loader or a Sponge jar does not — see [Minecraft Server Software Compared](/knowledge-base/minecraft/choosing-server-software/) for why plugins and mods never mix.

**Can I upload a jar and still update Minecraft versions from the panel?**
No. Version updates run the installer, and the installer replaces the jar. On a custom-jar server, updating means downloading the new build from the project yourself and repeating the upload. [Updating Your Minecraft Server](/knowledge-base/minecraft/updating-your-server-version/) covers the rest of the update — the Java runtime, the plugins, the world upgrade — all of which still applies.

**Is my world safe if I try a custom jar and go back?**
The world is untouched by any of this; the jar is the only thing that changes. The usual caveats about world *format* still apply: a jar for a newer Minecraft version will upgrade your world on first load and there is no way back except a backup. Take one from the **Backups** tab first — see [How to Create a Backup](/knowledge-base/general/how-to-create-a-backup/).

## What to Read Next

- [Minecraft Server Software Compared](/knowledge-base/minecraft/choosing-server-software/) — what each framework is for, and why hybrids are discouraged
- [Error: Unable to access jarfile](/knowledge-base/minecraft/error-unable-to-access-jar-file/) — the five one-line launcher errors and what each means
- [Updating Your Minecraft Server](/knowledge-base/minecraft/updating-your-server-version/) — versions, the Java 25 boundary and safe upgrades
- [Minecraft Server RAM and JVM Flags](/knowledge-base/minecraft/allocating-ram-and-jvm-flags/) — the launch command in full, and how the heap is sized
- [How to upload files via SFTP](/knowledge-base/general/how-to-upload-files-via-sftp/) — for anything the File Manager struggles with
- [Reading Minecraft Server Logs and Crash Reports](/knowledge-base/minecraft/reading-crash-logs-and-common-errors/) — once it launches and then falls over
- [Minecraft Server Networks: Setting Up a Velocity Proxy](/knowledge-base/minecraft/multi-server-networks-with-velocity/) — the supported way to run plugins and mods side by side

**Primary sources used for this guide** (all checked 19 August 2026): the GameServerKings Minecraft (Java) egg definition and install script from our own panel API; Oracle's specification for the [`java` launcher](https://docs.oracle.com/en/java/javase/25/docs/specs/man/java.html); [PaperMC's Fill API](https://fill.papermc.io/v3/projects); [Mojang's version manifest](https://launchermeta.mojang.com/mc/game/version_manifest_v2.json); [the Leaf release feed](https://github.com/Winds-Studio/Leaf/releases); and [SpongePowered](https://spongepowered.org/).

---

Made with 💜 by GameServerKings