Troubleshooting
This page covers the most common problems server owners run into with Quests, and how to solve them.
:::tip First step Open the admin window and run the check for all content. It finds unknown items, NPCs and quests, objective types that never count, empty pools and broken chapter chains, each with Go to. :::
Quests not appearing
Section titled “Quests not appearing”Symptoms: The Questbook is empty or a quest you added does not show up.
Possible causes:
- Custom content disabled —
config.jsonneeds"useCustomContent": true - File in the wrong folder — custom quest files belong in
custom/, notconfigs/ - Additional file starts with
custom_— files starting withcustom_are reserved for the standard merge. Rename your pack (e.g.my_pack.json) - JSON syntax error — the server log names the file
- Quest ID collision — if two quests share the same ID, only the last-loaded one survives
- Hidden quest — quests with
options.hiddenstay hidden while they are locked - Wrong tab — side, hub and pack quests are listed under Side quests
Fix: Run /ksquestadmin reload and check the server console for the loading summary.
Objectives not tracking
Section titled “Objectives not tracking”Symptoms: A quest is active but progress stays at 0.
Possible causes:
- Wrong target name — item, block and entity IDs must match the game’s names exactly. The admin window’s pickers only offer valid targets
- Wrong objective type — for example
killsfor combat,blocks_minedfor mining,items_collectedfor pickups.items_consumedandcomplete_hub_questsare not counted in Quests 2.1 - Self-placed blocks — blocks a player placed do not count for mining objectives until 30 minutes have passed (handled by KyuubiSoft Core)
- Quest not started — the player must start the quest first; seeing it is not enough
- Sequential quest — with
sequential, later objectives only count once the earlier ones are done
Fix: Enable live tracking output for yourself:
/ksquestadmin debugmodeIt logs every tracking event (blocks, kills, crafts and more) to the server console with the matching quests. Run it again to switch it off.
NPC dialog not showing
Section titled “NPC dialog not showing”Symptoms: Talking to a quest NPC shows no quest dialog or the wrong one.
Causes: the profile’s citizenId does not match an NPC, no entry fits the player yet (facts, prerequisites, quest state), or the profile file is missing.
Fix: On the NPC profiles tab of the admin window, check “Profile without NPC” and Who uses this NPC?, and use the phase preview for the player. Without a default dialog, an NPC with no fitting entry does what Core’s NPC management set up (shop, bank, dialogs). /ksquestadmin debug shows the player’s facts and quest state.
Daily/weekly quests not resetting
Section titled “Daily/weekly quests not resetting”Symptoms: Players keep the same daily or weekly quests after the reset time.
Possible causes:
- Reset time not reached — the daily reset defaults to 04:00 in the configured time zone. The General settings tab previews the next resets
- Pool too small — if the pool has fewer drawable quests than
dailyQuestCount(default 3) orweeklyQuestCount(default 5), fewer quests are handed out and the log warns once - Weights of 0 — quests with weight 0 are never drawn; a pool where every weight is 0 draws nothing
- Unknown quest IDs in the pool — they are skipped; the admin window’s check lists them
- Ready-to-claim quests — they are kept over a reset on purpose until the player claims them
Fix: Check the Pools tab of the admin window, or force a reset with /ksquestadmin resetdaily / resetweekly.
Texts show as raw keys
Section titled “Texts show as raw keys”Symptoms: You see key names like quest.my_quest.name instead of text.
Fix:
- Put your own keys into
custom_<lang>.jsoninlocalization/(no version needed for custom files), then run/ksquestadmin reload. - A text that exists in only one language falls back to that language since 2.1.0. If you still see a key, it exists in no language file.
- After a mod update, the shipped language files are replaced when the mod ships a newer version; your edits in shipped files are in the
.backup-v<N>copy.
Questbook is empty
Section titled “Questbook is empty”Symptoms: Opening the Questbook shows no quests at all.
Causes: config files not extracted yet (restart the server), loading failed (check the log), or a broken player file. Broken player files are moved to players_corrupt/ and the .bak copy is used when possible.
Fix: Run /ksquestadmin reload and check the console summary.
Rewards not granting
Section titled “Rewards not granting”Symptoms: A player completes a quest but does not receive a reward.
Possible causes:
- Inventory full — what does not fit waits as a pending reward and is handed out at the next login. Admins can hand it out at once with Deliver now in the Players tool
- Invalid item ID —
item_id(oritemId) must be a valid game item; the check lists unknown items - NPC turn-in — quests turned in at an NPC pay only there
- Missing plugin — XP rewards without the XP plugin and achievement or title rewards without KyuubiSoft Achievements pay tokens instead (see Rewards)
- Currency without an economy plugin — named currencies need an economy plugin; the failure is logged
Valid reward types: quest_tokens, item, lootbag, currency, rpg_xp, mmo_xp, endless_xp, leveling_xp, title, achievement, command.
The admin window does not save
Section titled “The admin window does not save”| Message | Meaning |
|---|---|
| ”Saving locked: n errors in the draft” | The check found errors. Save shows where; fix them or revert those changes |
| ”Saving is not allowed here (showcase server or missing permission)“ | You lack ks.quest.admin, or the server is in showcase mode |
| A console command entry is locked | You lack ks.core.admin.dialog.console (see Permissions) |
| Saving stops and names a file | config.json, a language file or an admin file could not be read. Fix the file; Quests does not replace it silently |
Debug tools
Section titled “Debug tools”| Tool | What it does |
|---|---|
| Admin window → check | Finds broken content before players do |
/ksquestadmin debug | Your active and completed quests, facts, chapters, streak |
/ksquestadmin debugmode | Live tracking output in the server console |
/ksquestadmin testzone <name> | Simulates entering a zone |
/ksquestadmin testnpc <id> | Simulates talking to an NPC |
| Quest editor → Test for me | Start, nearly done or reset one quest for yourself |
/ksquestadmin reload | Reloads all configuration and language files |
For more log output, set Core’s logLevel to all. The debug field in Quests’ own config.json has no effect.