Java could not load an agent named in the server's Java options

Error opening zip file or JAR manifest missing : /data/agents/profiler-agent.jar
Error occurred during initialization of VM
agent library failed Agent_OnLoad: instrument
2026-11-03T09:14:27.402Z  WARN  mc-server-runner  Minecraft server failed. Inspect logs above for errors that indicate cause. DO NOT report this line as an error.  {"exitCode": 1}

What it means

A Java agent is a jar that Java loads before the program itself, named with -javaagent:<path> in the Java options. Profilers, monitoring tools and some anti-cheat or patch tools work this way. When Java cannot open the agent’s jar, it refuses to start at all: it prints that the jar could not be opened and that the agent library failed to load, then exits. The game never runs, so the server’s own log is empty.

Why it happens

• The jar is not at the path given. It was never uploaded, it was moved or renamed, or the path has a typing mistake.
• The folder holding the jar is not mounted inside the container, or another mount covers it.
• The file is not a valid jar, for example a download that was cut short or an HTML error page saved under a .jar name.
• The server cannot read the file because of its permissions.

How to fix

1. Read the path the error prints and check that the file exists at that path inside the server’s container.
2. If you added the agent yourself, correct the path in the Java options (with the itzg image, JVM_OPTS or JVM_XX_OPTS), or remove the -javaagent: option to start without it.
3. Download the agent’s jar again if it may be damaged, and check that the file is readable.
4. Docker: check that the volume holding the jar is mounted at the path the option names, and that no other mount hides it.

In Perland

The issue appears in the server’s Diagnosis tab with the path Java could not open. Perland adds its own memory reader, /perland/heap-agent.jar, to every Minecraft server and checks it before each start, so if that path is the one named, starting the server again lets Perland put it back. An agent you added yourself is in the JVM options of the server’s Settings.

References

• Java documentation: the java.lang.instrument package (Java agents)
• Docker Minecraft Server: JVM options