On this page

Troubleshooting & FAQ

By the end of this page you will have an answer to the questions people actually ask about Osmium, and a next step for each of the ways a server goes wrong.

Start with osmium doctor -s <server> for anything that will not start. It checks Java, memory, the port, the EULA and the files the lock names, and every finding says what to do about it.

Is any data sent anywhere?#

There is no account, no sign-in and no telemetry. Osmium never phones home, and nothing about you or your servers is collected.

Osmium does make network requests, but only when you ask it to do something that needs one:

  • Modrinth's API — when you search for, list versions of, or install a mod or plugin, and to download the jar itself.
  • Server-software download endpoints — when you create or migrate a server, to fetch the jar.
  • Mojang's version manifest — when a version list is fetched, including for tab completion.
  • Your own server's status port — when osmium details asks who is online, on your own machine or network.
  • Your router, over UPnP or NAT-PMP — only when you run osmium expose --open or --off.

No API key is needed for any of these.

Where are files stored?#

Osmium's own settings and its registry of servers live in ~/.config/osmium on Linux, ~/Library/Application Support/osmium on macOS, and %AppData%\osmium on Windows. The download cache is separate, in ~/.cache/osmium, ~/Library/Caches/osmium or %LocalAppData%\osmium.

Each server lives wherever you created it, and holds its own osmium.json, osmium.lock, mods/ or plugins/, world folders, and a .osmium/ folder with the supervisor's state and log. Servers created with the "Default folder" option go in the servers folder inside Osmium's config directory.

Configuration has the full table.

Can Osmium adopt a server directory it did not create?#

Yes, in two steps.

Run osmium inside the folder, or point it there. If the folder has an osmium.json, Osmium registers it on the spot, so opening it once is enough for it to stay in the list.

For jars that were already in mods/ or plugins/ before Osmium saw them, run osmium mod track — it identifies each jar by its hash and records it in the lock, so Osmium manages it from then on. Jars it cannot identify are left alone and stay unmanaged. Jars Osmium did not install are never touched; every plan names them so you can see what is being left out.

A folder with a server jar but no osmium.json has nothing for Osmium to read. Create a server with the same engine and version, then move the world in.

Does Osmium run the server, or only manage it?#

It runs it. osmium start spawns a detached supervisor process that owns the server's stdin, writes everything it says to <server>/.osmium/server.log, and answers control requests on a socket until the server exits.

That is why a server keeps running when you close the interface or log out, and why osmium exec and osmium logs reach a server whoever started it.

What happens to my world when I change the Minecraft version?#

osmium migrate does not touch your world. It replaces the server jar and re-resolves your mods and plugins against the new target; the world folders, server.properties and everything else are left exactly as they were.

What does happen is Minecraft's own doing: the first time a newer server opens a world, it upgrades that world's format, and the upgrade is one-way. A world opened by 1.21 cannot be opened by 1.20 again. Take a backup before a version change you might want to walk back:

bash
$ osmium backup -s survival before-1.21

Why did a mod fail to install?#

Osmium prints why, but the causes are worth knowing apart:

  • Wrong kind. The server takes plugins and you used osmium mod add, or the other way round. Paper, Purpur, Spigot, Bukkit and Folia take plugins; Vanilla, Fabric, Forge, NeoForge and Quilt take mods.
  • No build for this loader. The project exists but has never been released for the loader your server runs.
  • No build for this Minecraft version. Common right after a Minecraft release, when authors have not caught up. osmium mod versions <slug> lists what this server actually could install.
  • A missing dependency that cannot be resolved. The plan says which dependency and why, and refuses the whole change rather than installing half of it.
  • A pin that cannot be satisfied. A pinned build may not exist for this Minecraft version. osmium mod unpin <slug> lets it be re-resolved.
  • A conflict. Two projects wanting incompatible builds of the same dependency. The plan is shown as blocked, and nothing is changed.
  • A beta or alpha build. Pre-release builds are excluded unless you pass --pre.

Java version mismatch is a different failure: it stops the server from starting, not the install. osmium doctor names it.

What happens if an update is interrupted?#

The server is left exactly as it was. Every change is worked out in full, then every file is downloaded and checked against the SHA-1 Modrinth publishes, and only then is anything written. A failure halfway through — a dropped connection, a hash that did not match, ctrl+c — means nothing was applied.

If a run was interrupted after some files had been written, osmium mod install puts the server back to exactly what the manifest and lock describe.

How do I get back to a clean state?#

In increasing order of severity:

bash
$ osmium mod install -s survival    # restore exactly what the lock describes
$ osmium doctor -s survival         # find out what is actually wrong
$ osmium restore -s survival        # put the newest backup back (server must be stopped)
$ osmium cache clean                # empty the download cache and fetch afresh

To rebuild a server from scratch while keeping what it was: osmium destroy -s survival --keep-manifest, then osmium create --from survival.osmium.json.

A server will not start. Where do I look?#

bash
$ osmium doctor -s survival
$ osmium logs -s survival -n 100

The most common causes, in the order they occur:

  • No Java, or the wrong Java. Minecraft 1.21 and newer need Java 21; 1.18 to 1.20.4 need 17. doctor compares them for you.
  • The EULA has not been accepted. The server refuses to run until it has.
  • The port is already in use — another server, or the same one still shutting down.
  • More memory promised than the machine has. osmium edit --ram lowers it.
  • Missing jars. osmium mod install puts back exactly what the lock names.

osmium is not found after installing#

The install directory is not on your PATH. With the Go toolchain that is $(go env GOPATH)/bin.

Tab completion does nothing#

Run osmium completion install and open a new shell — the script is only read at shell startup.

On zsh, completions are only read from directories in fpath. The install command prints the line to add to ~/.zshrc if the directory it used is not already there.

Nothing happens when I press a key in the interface#

Check the terminal size. The interface has a minimum of 60 columns by 18 rows, and needs UTF-8 and 256 colours.

Press ? — it lists the keys that work in the pane in front of you, which is usually shorter than the list you were expecting.

How do I report a bug?#

Open an issue at github.com/limelamp/osmium/issues with the output of osmium --version, your OS and terminal, the exact command or keys, and what you expected versus what happened. Filing a good bug report has the full list.