Diagnostics and Troubleshooting
In: Reference · Related: FAQ · Natural Generation & Preloading · Full config.yml Reference · Back: Home
A troubleshooting handbook organized as "symptom → likely cause → fix." Find your case in the quick table below first, then read the matching section. Use it together with these diagnostic commands:
| Command | Use |
|---|---|
/qr why <template> | At your feet, list item by item every landing check for that template (switch / world / dimension / coordinate box / height / ground / water / biome / flatness / spacing / density) with pass ✔ / fail ✘ + reason. Use it first thing when "I configured it but it won't generate." |
/qr gentest | Near you, run about 25 generation attempts using the director's living-world algorithm, and report how many succeeded / were blocked by density / drew no template / failed placement. See the actual hit rate (requires the director to be on). |
/qr near [radius] | List nearby generated anchors (name / distance / anchor id), default radius 200. Confirm whether a ruin actually generated and whether it's under your feet. |
/qr info [anchor] | No argument = global status (template count / anchor count / session count / tracked objective count); with an anchor id = that ruin's template / coordinates / status / session occupancy / blueprint stats / clear progress. |
/qr profile [reset] | See QR's actual per-stage timings (count / average / peak / total ms for placement paste.place / snapshot snapshot.capture / restore snapshot.restore). reset clears it to re-measure. The tool for proving your innocence. |
🌳 Quick decision tree
| Symptom | Most likely cause | Jump to |
|---|---|---|
| Ruins don't generate at all | Master switch / director off, a landing check fails, density full | §1 |
| Walking into a ruin spawns no mobs | Not within activation radius, blueprint spawn points missing, MM mob name wrong | §2 |
| Chest won't open / no reaction on right-click | Under protection, reward chest not yet at the unlock stage, not a registered container | §3 |
| Right-clicking a keystone on the core won't activate the realm | Not aimed at the core / tier threshold / danger budget / out of radius | §4 |
| Right-clicking the guide item gives no compass / no pointing | No ruin of that type, wrong guide item, occupied by another guidance | §5 |
| Clearing / opening a chest yields no loot | Wrong table name, growth threshold, already claimed (once per person), conditional group | §6 |
| Server lags / TPS drops | Most likely pre-generation (vanilla terrain) or snapshot over the volume cap | §7, §8 |
1. Ruins won't generate
The most common issue; check in this order:
- First
/qr why <template>— it lists every landing check item by item; the red ✘ line is the cause, far faster than guessing. - See whether any of these blocked it:
Failed check in /qr why | Meaning | Fix |
|---|---|---|
| switch / enabled | generation.enabled: false or the template's generation.enabled: false | Both config and template must be on |
| world / dimension | The current world / dimension isn't in the profile's environments / worlds | Edit the profile's / template's environments, worlds, or test in another world |
| biome | The current biome isn't in the biomes whitelist | Stand in a matching biome, or relax biomes (empty = unrestricted) |
| coordinate box spawn-region | Inside an exclude box (such as a spawn exclusion zone) | Walk out of the exclusion zone, or edit spawn-region |
| height / ground / water | Underfoot doesn't satisfy the generation layer (e.g. a sea-surface profile standing on land, spawn-in-water:false standing in water) | Move to suitable terrain, or adjust spawn-in-water/spawn-in-lava/spawn-in-void |
| flatness | The ground's variation exceeds max-variance | Move to flat ground, or raise max-variance / max-errors, or set radius:0 to disable the check |
| spacing / density | Nearby ruins already reach min-spacing / max-per-region | Move farther away, or lower the density limits (see below) |
- Not a landing problem, but "it didn't get picked": use
/qr gentestto see the actual hit rate. If it reports many "drew no template," it's a weight / priority issue — raise that template'sgeneration.weight, or check whetherdirector.weightsholds a non-empty list (if it does, only the listed templates take part in the draw). If it reports many "blocked by density," raisedirector.density.max-per-regionand lowermin-spacing. - The director isn't on / the master switch is off:
/qr gentestand/qr scatterboth requiredirector.enabled: true, and will say the director is disabled when off; withgeneration.enabled: false, all natural generation stops and you can only place manually with/qr spawn. - Want to see results immediately:
/qr spawn <template>bypasses all checks and places right at your feet;/qr scatter <radius> <count>batch pre-generates an area around you.
For a parameter cheat sheet, see Natural Generation & Preloading §6.
2. No mob spawns
| Likely cause | Fix |
|---|---|
| Not within activation radius | Mobs sleep while the anchor is DORMANT; only when a player enters the activation radius does it switch to ACTIVE and spawn. Use /qr info <anchor> to check whether the status is ACTIVE; get closer to the core area and check again |
| Blueprint has no spawn points | The blueprint's spawn-points is empty. Check whether the template folder has a blueprint.yml, and whether the spawn-point coordinates fall inside the structure (relative to the structure origin 0,0,0) |
| Wrong stage | A spawn point carries a stage and only spawns once the matching stage is entered. Use /qr info <anchor> to see the current stage |
| MM mob name misspelled | The name in mob: mm-<MythicMobsName> doesn't exist in MM → won't spawn. After /mm reload, double-check the name's case |
| MythicMobs not installed | mm- prefixed mobs require MM; without it you can only use vanilla entity names (e.g. ZOMBIE). See FAQ |
| Respawn interval not reached | The template's respawn controls the reset interval; after clearing you must wait respawn before mobs spawn again |
See Spawning & Clearing.
3. Chest won't open
| Likely cause | Fix |
|---|---|
| Ruin under protection | Ruins being explored / activated are protected, with some interactions restricted. Confirm the anchor status (/qr info <anchor>); it unlocks once CLEARED |
| Reward chest not at unlock stage | A blueprint reward chest carries unlock-stage and can't be opened before that stage. Advance kill objectives to the matching stage first |
| Once per person already claimed | A per-player-once: true reward chest gives once per person; repeated right-clicks do nothing (this is expected) |
| Container not a registered type | Container loot's containers limits the active types (e.g. [CHEST, BARREL]). Other containers don't take part in rolling |
| Wrong / missing loot table name | The template's loot.container-table or the reward chest's loot-table points to a nonexistent table. Editor-marked chests fall back to the default table; custom table names must match the file name in loottables/ |
See Loot System.
4. Realm won't activate
Right-clicking a keystone on the ruin core does nothing / says activation failed:
| Likely cause | Fix |
|---|---|
| Not aimed at the core / out of radius | /qr activate's search radius is realm.activate-radius (default 48). Get close to the core coordinates set in the blueprint's cores, or hold the keystone and right-click the core block |
| Blueprint has no core | The blueprint's cores is empty → no activation point. Add a core coordinate |
| Ruin not cleared | Realm injection usually requires the ruin to be CLEARED first. Clear it before activating |
| Keystone tier threshold | Affixes have min-tier; if the keystone's tier is too low there are no injectable affixes. Use /qr keystone give <tier> [player] to grant a higher-tier keystone for testing |
| Insufficient danger budget | The affix pool is constrained by realm.tiers.danger-budget; once the budget is exhausted no more affixes stack (this prevents hellstacks, not a bug) |
| Mutex group | Affixes in the same group are mutually exclusive (e.g. veteran/overlord); only one is chosen |
See Realms & Keystones and Affix System.
5. Guidance not working
Right-clicking the guide item gives no compass / doesn't point to a ruin:
| Likely cause | Fix |
|---|---|
| No ruin of that type | The guide item qinhruins:guide_<templateId> points to the nearest ruin of the same type; if none exist in the world, there's nothing to point to. First /qr near or /qr scatter to confirm an anchor of that template exists |
| Wrong guide item given | The guide item is granted by an item source (qinhruins:guide_<templateId>); QR ships no give command. Hand it out via QI / a loot table / a command item plugin, and spell the template id correctly |
| Guidance already in progress | Only one guidance at a time. /qr guide cancel cancels the current one and returns the guide item, then use a new one |
| Stuck guidance state | Admins can /qr guide clear <player> to force-clear a player's guidance state (no item refund) |
See Guide & Codex.
6. No loot drops
| Likely cause | Fix |
|---|---|
| Wrong table name / path | The table name pointed to by loot.container-table / reward.clear-table / a reward chest's loot-table must match the file name in loottables/ (without .yml) |
| Blocked by growth threshold | An entry with min-growth higher than the player's growth won't drop. The realm realm table's netherite scrap / enchanted golden apple have thresholds (≥30 / ≥50) |
| Once per person already claimed | In per-player-once: true / per-player mode, each person gets one copy on first opening; once claimed it won't drop again |
| Conditional group not satisfied | A groups condition runs through PlaceholderAPI; with PAPI installed and the condition false, that group isn't rolled. Without PAPI the condition is always true (so it should drop) |
| Server-wide shared already taken | In shared mode it's a real first-come-first-served container; once someone takes it, it's gone (neutral, not affected by growth) |
| Item source didn't resolve | item is resolved through CoreLib; if the plugin for a qi:/nexo: prefix isn't installed, resolution fails. For vanilla use vanilla:DIAMOND |
See Loot System.
7. Server lag
If the lag happens during world pre-generation / startup map seeding, read §8 first — that's most likely not QR's fault.
QR's own placement is frame-spread and throttled, and shouldn't freeze the server in normal operation. If you suspect QR:
- First
/qr profileto see the real timings — it lists count / average / peak / total ms forpaste.place(structure placement) /snapshot.capture(pre-generation snapshot) /snapshot.restore(removal restore). Whichever has the high peak is the culprit. After reading,/qr profile resetclears it for further observation. - Snapshot over the volume cap freezes the thread: a synchronous snapshot of a huge structure (millions of blocks) freezes the main thread. The config has
cleanup.max-snapshot-volume(default 500000) — above this it skips the snapshot (removal won't restore but won't lag). If it's stuck onsnapshot.capture, lower it, or disablecleanup.snapshot-restorefor the huge structures. - Candidate generation spike: a flood of new chunks (e.g. pre-generation) instantly fills the candidate queue. Lower
generation.max-per-tick,generation.max-millis-per-tick(the per-tick millisecond budget, yielding when exceeded), or lowerdirector.live.chance. The console's "candidate queue full" warning, once per minute, signals exactly this. - Too many ruins:
director.density.max-per-regiontoo large, orregen-hourstoo long, causing cleared ruins to never regen and pile up. Enableregen-hours+cleanup.snapshot-restoreto have cleared ruins periodically restore and free slots.
See Natural Generation & Preloading §4 Snapshots & Regen.
8. Pre-generation / startup lag (must read)
🔴 Key understanding: the lag, TPS drop, and long durations during pre-generation come from the server frantically generating vanilla terrain chunks (Chunky and the like at work) — not from QinhRuins.
QR's ruins follow the chunks — a generation attempt is triggered only by a new chunk loading (chunk-chance) or player activity (live). When you use a pre-generation plugin like Chunky to lay down a large number of chunks at once, what actually eats CPU is vanilla terrain generation itself. QR's own placement is frame-spread and throttled (generation.max-millis-per-tick millisecond budget + candidate queue, yielding the tick when exceeded) and won't freeze the server — it'll only be throttled and slowed in landing ruins during pre-generation.
Proving your innocence: run /qr profile during pre-generation — you'll see that QR's stages (paste.place, etc.) take only a tiny share of the time; the bulk of the lag isn't here.
The right approach (announce in advance, warn that the resource world will be closed, use a small radius in batches on weak hardware, and lighten QR's load during pre-generation), along with the full recommended order, is in ➜ Natural Generation & Preloading §7 World Pre-generation (Chunky) and Anti-lag Tips ⚠️ Must Read.
Still not solved?
/qr why <template>— go through the landing checks item by item/qr gentest— see the actual hit rate (requires the director on)/qr near//qr info— confirm anchor status/qr profile— see the real per-stage timings- Look up terms in the Glossary, or read the FAQ