Storage, reload, and troubleshooting
Storage
Runic keeps every placed rune, binding, and player record in one SQLite database at plugins/Runic/storage/runic.db. Each rune has its own table, and players share one table. While the server runs, two companion files sit beside the database: runic.db-wal and runic.db-shm. Recent changes live in the -wal file until Runic folds them into the database.
Runic saves only the rows a change touches, and writes them away from the main server thread.
A few things live outside the database:
| Path | Holds |
|---|---|
plugins/Runic/storage/hell-maw-recovery/ | Journals that let Hell Maw restore its terrain after a crash |
plugins/Runic/salvation/ | Salvation's saved records |
| Genesis pocket worlds | Real worlds named genesis_<owner>_<id>. On Paper 26 and newer they sit under world/dimensions/runic/, and on other servers beside your main world. |
Backups
Stop the server, then copy the whole plugins/Runic/ folder together with your world folders, Genesis pockets included. Runic's records point at blocks and at world IDs, so a backup of one without the other restores bindings that no longer match their blocks.
Keep runic.db, runic.db-wal, and runic.db-shm together whenever you copy the database.
Moving servers
Copy plugins/Runic/ along with the worlds. Runic finds each world by the ID stored in its uid.dat, so keep those files with the worlds.
Reloading
/runic reload re-reads config.yml, tiers-blocks.yml, tiers-items.yml, and every rune file, then refreshes the live magic built on them. Placed runes stay where they are.
- Each file passes its checks before Runic uses it. A file that fails stops the reload, and the console names the file and the setting.
- Success reads Runic reloaded configs, tiers, rune feedback, and candidate-backed state.
- Failure reads Runic could not finish the reload; rune and tier settings are unchanged, though config.yml and some stored state may already be re-read. Check the server log. The rune files and tier files keep their previous values, so fix the file the console names and reload again.
- A reload never creates rune files. A rune file you deleted uses its defaults until the next restart writes a fresh copy.
- A reload reads the tier files as they stand. Materials the files lack get their default Tier in memory, and the next restart adds their rows, as described in Rune files.
- The
hooks:switches take effect on reload.hooks.worldguardcan be switched off and back on, but if it was off when the server started, switching it on needs a restart. See Integrations.
Troubleshooting
Runic will not start
When a file fails its checks during startup, Runic disables itself and the console says why.
Older settings in config.yml. Runic refuses these keys from older releases and names where each setting lives now:
| Old key | Current home |
|---|---|
disabled-runes | rune-enabled: false in each rune's file |
faithpoint | runes/faithpoint.yml |
faith-transfer | runes/faithtransferportal.yml |
pegasus | runes/pegasus.yml |
reality-master | runes/realitymaster.yml |
advanced-reality-master | runes/realitymasteradvanced.yml |
Copy any values you still want into the named files, then delete the old keys.
A value of the wrong type. Invalid current config.yml: teleport.cross-world must be a boolean means a setting holds the wrong kind of value. Fix the value it names. Settings you leave out simply use their defaults. config.yml may be at most 1 MiB.
A rune file. Invalid current runes/teleporter.yml: … names the rune and the setting. See Rune files for the rules.
A tier file. Invalid tiers value for STONE in tiers-blocks.yml; expected an integer from 0 to 7 names the row to fix.
The database. Unsupported Runic database schema … means runic.db came from a build that stores data differently. Go back to the Runic jar that wrote it, or move the storage folder aside to start with an empty database.
A rune does nothing
Work through these in order. Each refusal below is the default message, and each rune file can reword it.
- Permission. Teleporter stirs, then turns from you — you lack permission to wield it. Grant
runic.runes.<rune>. See Installation. - Initiation. The pattern stirs beneath your hand, but the magic does not know you. Seek the rite of Initiation. The player needs Initiation, or set
require-initiation: false. - The world. Runic stays silent in every world listed under
disabled-worlds. - The rune is switched off. The pattern is drawn true, but Teleporter is forbidden on this server. Check
rune-enabledin the rune's file. - The Minecraft release. Zen Master needs Minecraft 26.3 or newer (this server is 1.21.11).
- A ward. The rune stays cold — Void Ward smothers such magic here. See Wards.
- Region, claim, or lock protection. WorldGuard names itself in its message. See Integrations and protection.
- The pattern. A pattern that is nearly right earns a hint and particles on the faulty blocks while
near-miss-hintsis on. See Near-miss hints. A pattern far from any rune stays silent.
To watch activations as they happen, open Runic Sight and use /runic debug to choose which runes it reports.
Magic built by another player
Most bound magic answers only to its owner. See Ownership. Staff with runic.admin.bypass-owner can use, move, and retune it.
Warnings about a protection plugin
… Runic world changes are denied until the integration is healthy. means a protection plugin is installed and its check stopped answering. Runic refuses the actions that plugin would judge until it answers again. Update Runic, or set that plugin's switch under hooks: to false.
Reporting a problem
Include the build stamp and server version from the console banner, the steps that lead to the problem, and the console log around any error.