# When something is wrong

> The handful of things that actually go wrong, and what each one looks like.

Source: https://stygion.eu/docs/keystone/troubleshooting
Updated: 2026-10-30

Every one of these is a thing that has actually happened, written as what you see rather than as a category.

## The console never says "Keystone is running"

The file is for a different Minecraft version, or the server is not NeoForge. The two names differ by exactly the version, and it is easy to take the wrong one from a list. The loader usually says so a few lines earlier, in its own words.

From 0.3 Keystone runs on **NeoForge** only. A Fabric server keeps the last Fabric build (up to 0.2.x, still on CurseForge); a 0.3 jar on Fabric is simply not loaded.

## Missing dependency `stygion_library`

NeoForge stops at the loading screen and names a missing mod, `stygion_library`. From 0.3.4 Keystone needs STYGION Library beside it. Put `stygion-library-<version>.jar` into `mods/` next to Keystone — one file, the same for 1.21.1 and 26.2, [on CurseForge](https://www.curseforge.com/minecraft/mc-mods/stygion-library) — and start again. The console then shows `running on STYGION Library 1.0.0`. Keystone 0.3.3 and older do not need it. More on [installing it](/docs/keystone/install).

## `/keystone` says you may not

Keystone has its own permissions and does not read Minecraft's operator level, on purpose — so that "may restart the server" and "may fly" are separate questions. From the console, which is always allowed:

```
keystone permission group admin add <your name>
```

**On 0.1.0 you have to make the group first** — the only one on a fresh server is `default`, which everybody is in:

```
keystone permission group admin create 100
keystone permission group admin allow keystone.*
keystone permission group admin add <your name>
```

From 0.1.1 `admin` already exists with `keystone.*` in it and nobody in it, so the one line is enough.

Mind the word in the middle: it is `permission group`, not `group`.

## The editor link does not open

`/keystone panel` builds the link out of the address the local API listens on, and that is `127.0.0.1` by default — the machine the server runs on. On a hosted server you have two ways round it:

**A tunnel**, which exposes nothing and is the safer one:

```
ssh -L 25586:127.0.0.1:25586 you@your-server
```

**Or (from 0.1.1) tell the mod the way in.** If you move the API to `0.0.0.0` so it can be reached from elsewhere, the link itself would come out as `http://0.0.0.0:25586/…`, which opens nowhere. That is what `api.reachable-at` is for:

```
/keystone set keystone.api.reachable-at 192.168.1.50
```

Empty and listening on a real address → it uses that. Empty and listening on `0.0.0.0` → it asks the machine for its own address. Set wins, which is what you need behind a router, through a tunnel, or under a name you gave the machine. A new link is composed when you ask for it, so the change applies straight away.

**Before you move the API off loopback, read [the local API](/docs/keystone/api).** It can do everything the mod can do.

Then click the link again — a new one, because they last five minutes and work once. If the port is not 25586 you changed it, and the console says which one it listens on at startup.

## Discord is quiet

Three things, in the order they go wrong:

1. The bot token is blank. It is a secret, so the editor shows whether one is set and never what it is.
2. The bot has no **Message Content** or **Server Members** intent. Both are switches on the application where you made the bot, and without them the bot connects and hears nothing — which looks exactly like being offline.
3. The channel ids are for a server the bot is not in.

The console says which of the three it is when the module starts.

## A setting did not take

Nothing is ever half-applied: a value that does not fit is refused before it is written, with the reason and the field. Look at the console for the refusal — for example that `every 6h` is a schedule and `6h` on its own is not.

**A setting's name is the whole path** — `bench.share-live`, not `share-live`. Get it wrong and the console names the nearest thing that does exist.

If it *was* applied and you want it back:

```
keystone set history
keystone set undo <number>
```

Every change is there with who made it, from where, and what the value was before.

## The server is slow and you do not know why

```
/keystone test 20
```

It measures the server empty first, then places players in groups, and finishes with a sentence naming what gave out — the processor, memory, the garbage collector, or loading chunks. Those are four different problems with four different answers, and knowing which is most of the work. The report also says which mod the time went into, which world it went into, and what is standing on the server.

If it says the machine was already past playable with nobody on it, something is wrong that no number of players caused, and the console around the start of the run is where to look.

## The log is a wall of the same line

Some mods write one error hundreds of times a second. It hides everything else and costs time to write. From 0.3.4 Keystone merges those lines in the console and `latest.log`; the settings are in `keystone.toml`:

- `logs.merge-repeats` (on): a warning or error repeating from any mod is written whole once, then counted. Once per `logs.repeat-window` (10 s) one line says `^ the line above repeated Nx in the last 10 s (from <mod>) - merged by Keystone: <line>`. A line that stops and comes back is written whole again.
- **What counts as the same line**: with an exception, the same exception thrown from the same place; without one, the same text with only numbers different. Two different players, commands or items never merge.
- **What is never merged**: ordinary lines (INFO and below), unless their logger is listed in `logs.merge-loggers`; and whatever the loggers in `logs.never-merge` write at any level — joins, commands, kicks and bans, the player list and Keystone's own lines by default. Add your moderation or audit mod's logger there.
- **`debug.log` is never filtered**: every line stays there whole, so nothing is lost for an investigation.
- `logs.alert-at` (1000; 0 turns it off): that many repeats in one window raises an alert to the Discord alerts channel, naming the mod — at most once an hour per line.
- `logs.async` (on, applies after a restart): the console, `latest.log` and `debug.log` sit behind one asynchronous appender, each keeping its own level. A server that is killed can lose the last moment of lines.

The [profiler](/docs/keystone/profiler) report has a **Log floods** table with the mod, how many lines were merged, the worst window and the line itself — the quickest way to see who is doing it.

## The assistant says there is nothing to ask

It is off until you fill in `assistant.address`, `assistant.key` and `assistant.model`. There is no key of ours and nothing routes through STYGION — you point it wherever you like, including at a model running on the same machine, in which case there is no key to fill in at all.

## Something else

The console line is usually the answer, and Keystone's lines all start with `[Keystone]` and the part that wrote them, so you can tell which switch turns it off. If you want the machine's own view of it, the **Console** screen in the editor is the same lines with chat beside them, and `/keystone assistant incident` will read that stretch and say what looks wrong.

**Keystone's own failures can be sent to an error tracker you run** (GlitchTip or Sentry), so you hear about them without watching the log. It is **off**: the jar carries no address and sends nothing until you set `errors.dsn` in `keystone.toml` (`/keystone set errors.dsn <address>`; empty switches it off again, no restart). Only failures with Keystone's own code in the stack are sent: the exception, its stack, the Keystone version, the loader and the Minecraft version. Messages are cleaned first (paths, addresses, e-mails, tokens, anything in quotes and every player name this server has seen are removed). No log lines, no chat, no server name, no player; the same failure goes at most once in ten minutes. `errors.environment` names what the reports are filed under.
