# Když něco nehraje

> Těch pár věcí, co se doopravdy pokazí, a jak každá vypadá.

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

Každá z těchhle věcí se doopravdy stala, a je napsaná tak, jak ji uvidíš, ne jako kategorie.

## Konzole nikdy neřekne „Keystone is running"

Soubor je pro jinou verzi Minecraftu, nebo server neběží na NeoForge. Ta dvě jména se liší přesně verzí a je snadné vzít ze seznamu špatné. Loader to obvykle o pár řádek dřív říká sám, svými slovy.

Od 0.3 běží Keystone jen na **NeoForge**. Server na Fabricu si nechá poslední build pro Fabric (do 0.2.x, pořád na CurseForge); jar 0.3 se na Fabricu prostě nenačte.

## Chybí závislost `stygion_library`

NeoForge se zastaví na načítací obrazovce a pojmenuje chybějící mod `stygion_library`. Od 0.3.4 potřebuje Keystone vedle sebe STYGION Library. Dej `stygion-library-<verze>.jar` do `mods/` vedle Keystone — jeden soubor, stejný pro 1.21.1 i 26.2, [na CurseForge](https://www.curseforge.com/minecraft/mc-mods/stygion-library) — a nastartuj znovu. Konzole pak ukáže `running on STYGION Library 1.0.0`. Keystone 0.3.3 a starší ji nepotřebují. Víc v [instalaci](/docs/keystone/install).

## `/keystone` ti řekne, že nesmíš

Keystone má vlastní oprávnění a schválně nečte operátorskou úroveň Minecraftu — aby „smí restartovat server" a „smí létat" byly dvě různé otázky. Z konzole, která smí vždycky:

```
keystone permission group admin add <tvoje jméno>
```

**Na 0.1.0 tu skupinu musíš nejdřív vyrobit** — jediná, která na čerstvém serveru existuje, je `default` a jsou v ní všichni:

```
keystone permission group admin create 100
keystone permission group admin allow keystone.*
keystone permission group admin add <tvoje jméno>
```

Od 0.1.1 už `admin` existuje s `keystone.*` a je prázdná, takže stačí ta jedna řádka.

Pozor na to slovo uprostřed: je to `permission group`, ne `group`.

## Odkaz na editor se neotevře

`/keystone panel` staví odkaz z adresy, na které lokální API poslouchá — a ta je ve výchozím stavu `127.0.0.1`, tedy stroj, kde běží server. U hostovaného serveru máš dvě cesty:

**Tunel** — nic nevystavuješ a je to ta bezpečnější:

```
ssh -L 25586:127.0.0.1:25586 ty@tvuj-server
```

**Nebo (od 0.1.1) řekni modu, kudy se k němu chodí.** Když API posadíš na `0.0.0.0`, aby na něj šlo dosáhnout odjinud, samotný odkaz by vyšel jako `http://0.0.0.0:25586/…`, což se neotevře nikde. Od toho je `api.reachable-at`:

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

Prázdné a poslouchající na skutečné adrese → použije ji. Prázdné a poslouchající na `0.0.0.0` → zeptá se stroje na jeho vlastní adresu. Vyplněné vyhrává, což je to, co potřebuješ za routerem, v tunelu nebo pod jménem, které jsi tomu stroji dal. Nový odkaz se skládá až ve chvíli, kdy si o něj řekneš, takže změna platí hned.

**Než API pustíš mimo loopback, přečti si [Lokální API](/docs/keystone/api).** Umí všechno, co umí mod.

Pak klikni na odkaz znovu — na nový, protože platí pět minut a funguje jednou. Když port není 25586, změnil jsi ho, a konzole při startu říká, na kterém poslouchá.

## Discord mlčí

Tři věci, v pořadí, ve kterém se kazí:

1. Token bota je prázdný. Je to tajemství, takže editor ukáže, jestli je vyplněný, a nikdy čím.
2. Bot nemá **Message Content** nebo **Server Members**. Obojí jsou přepínače na aplikaci, kde jsi bota vyrobil, a bez nich se bot připojí a neslyší nic — což vypadá úplně stejně jako být offline.
3. ID kanálů patří serveru, na kterém bot není.

Konzole při startu modulu řekne, která z těch tří to je.

## Nastavení se neprojevilo

Nikdy se nic neaplikuje napůl: hodnota, která neodpovídá tomu, co ta věc je, se odmítne dřív, než se zapíše, i s důvodem a polem. Podívej se do konzole na to odmítnutí — třeba že `every 6h` je rozvrh a samotné `6h` není.

**Jméno nastavení je celá cesta** — `bench.share-live`, ne `share-live`. Když se spleteš, konzole vypíše, co existuje nejblíž.

A když se to aplikovalo a chceš to zpátky:

```
keystone set history
keystone set undo <číslo>
```

Každá změna je tam i s tím, kdo ji udělal, odkud a jaká byla hodnota předtím.

## Server je pomalý a nevíš proč

```
/keystone test 20
```

Změří server prázdný, pak postaví hráče po skupinách a skončí větou, která pojmenuje, co povolilo — procesor, paměť, garbage collector, nebo načítání chunků. To jsou čtyři různé problémy se čtyřmi různými odpověďmi a vědět který je většina té práce. Report k tomu řekne, do kterého modu ten čas šel, do kterého světa, a co na serveru stojí.

Když napíše, že mašina byla přes hratelné už bez lidí, je špatně něco, co hráči nezpůsobili, a hledá se to v konzoli kolem začátku toho běhu.

## Log je zeď téže řádky

Některé mody píšou jednu chybu stokrát za vteřinu. Zakryje to všechno ostatní a samotné zapisování stojí čas. Od 0.3.4 tyhle řádky Keystone v konzoli a v `latest.log` slučuje; nastavení jsou v `keystone.toml`:

- `logs.merge-repeats` (zapnuto): varování nebo chyba, která se opakuje z jakéhokoli modu, se zapíše jednou celá a pak se počítá. Jednou za `logs.repeat-window` (10 s) napíše jedna řádka `^ the line above repeated Nx in the last 10 s (from <mod>) - merged by Keystone: <řádka>`. Řádka, která přestane a vrátí se, se zapíše znovu celá.
- **Co je tatáž řádka**: s výjimkou tatáž výjimka vyhozená z téhož místa; bez ní tentýž text, který se liší jen čísly. Dva různí hráči, příkazy nebo předměty se nikdy nesloučí.
- **Co se nikdy neslučuje**: běžné řádky (INFO a níž), pokud jejich logger není v `logs.merge-loggers`; a cokoli, co píšou loggery z `logs.never-merge` na jakékoli úrovni — připojení, příkazy, kicky a bany, seznam hráčů a vlastní řádky Keystone ve výchozím stavu. Logger svého modu na moderaci nebo audit tam přidej.
- **`debug.log` se nikdy nefiltruje**: každá řádka v něm zůstane celá, takže pro vyšetřování se nic neztratí.
- `logs.alert-at` (1000; 0 to vypne): tolik opakování v jednom okně vyvolá upozornění do Discord kanálu pro alerty s názvem modu — nejvýš jednou za hodinu pro každou řádku.
- `logs.async` (zapnuto, platí po restartu): konzole, `latest.log` a `debug.log` sedí za jedním asynchronním appenderem a každý si drží svou úroveň. Server, který někdo zabije, může ztratit řádky z posledního okamžiku.

Report [profileru](/docs/keystone/profiler) má tabulku **Log floods** s modem, počtem sloučených řádků, nejhorším oknem a tou řádkou — nejrychlejší způsob, jak zjistit, kdo za to může.

## Asistent říká, že není na co se ptát

Je vypnutý, dokud nevyplníš `assistant.address`, `assistant.key` a `assistant.model`. Žádný náš klíč neexistuje a nic neteče přes STYGION — namíříš si ho, kam chceš, klidně na model běžící na téže mašině, a pak není co vyplňovat ani jako klíč.

## Něco jiného

Odpověď bývá v té řádce v konzoli, a Keystone má všechny svoje uvozené `[Keystone]` a částí, která je napsala, takže poznáš, který přepínač to vypíná. Když chceš pohled té mašiny, obrazovka **Console** v editoru jsou tytéž řádky i s chatem vedle, a `/keystone assistant incident` ten úsek přečte a řekne, co vypadá špatně.

**Vlastní chyby Keystone se dají posílat do nástroje na chyby, který si provozuješ** (GlitchTip nebo Sentry), a nemusíš pak hlídat log. Je to **vypnuté**: jar žádnou adresu nenese a nic neposílá, dokud nenastavíš `errors.dsn` v `keystone.toml` (`/keystone set errors.dsn <adresa>`; prázdné to zase vypne, bez restartu). Posílají se jen chyby, které mají ve stopě kód Keystone: výjimka, její stopa, verze Keystone, loader a verze Minecraftu. Zpráva se předtím vyčistí (cesty, adresy, e-maily, tokeny, cokoliv v uvozovkách a každé jméno hráče, které server zná, se odstraní). Žádné řádky logu, chat, jméno serveru ani hráč; stejná chyba odejde nejvýš jednou za deset minut. `errors.environment` říká, pod čím se hlášení založí.
