Skip to content

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. :::


Symptoms: The Questbook is empty or a quest you added does not show up.

Possible causes:

  1. Custom content disabled — config.json needs "useCustomContent": true
  2. File in the wrong folder — custom quest files belong in custom/, not configs/
  3. Additional file starts with custom_ — files starting with custom_ are reserved for the standard merge. Rename your pack (e.g. my_pack.json)
  4. JSON syntax error — the server log names the file
  5. Quest ID collision — if two quests share the same ID, only the last-loaded one survives
  6. Hidden quest — quests with options.hidden stay hidden while they are locked
  7. 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.


Symptoms: A quest is active but progress stays at 0.

Possible causes:

  1. Wrong target name — item, block and entity IDs must match the game’s names exactly. The admin window’s pickers only offer valid targets
  2. Wrong objective type — for example kills for combat, blocks_mined for mining, items_collected for pickups. items_consumed and complete_hub_quests are not counted in Quests 2.1
  3. Self-placed blocks — blocks a player placed do not count for mining objectives until 30 minutes have passed (handled by KyuubiSoft Core)
  4. Quest not started — the player must start the quest first; seeing it is not enough
  5. Sequential quest — with sequential, later objectives only count once the earlier ones are done

Fix: Enable live tracking output for yourself:

/ksquestadmin debugmode

It logs every tracking event (blocks, kills, crafts and more) to the server console with the matching quests. Run it again to switch it off.


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.


Symptoms: Players keep the same daily or weekly quests after the reset time.

Possible causes:

  1. Reset time not reached — the daily reset defaults to 04:00 in the configured time zone. The General settings tab previews the next resets
  2. Pool too small — if the pool has fewer drawable quests than dailyQuestCount (default 3) or weeklyQuestCount (default 5), fewer quests are handed out and the log warns once
  3. Weights of 0 — quests with weight 0 are never drawn; a pool where every weight is 0 draws nothing
  4. Unknown quest IDs in the pool — they are skipped; the admin window’s check lists them
  5. 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.


Symptoms: You see key names like quest.my_quest.name instead of text.

Fix:

  1. Put your own keys into custom_<lang>.json in localization/ (no version needed for custom files), then run /ksquestadmin reload.
  2. 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.
  3. 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.

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.


Symptoms: A player completes a quest but does not receive a reward.

Possible causes:

  1. 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
  2. Invalid item ID — item_id (or itemId) must be a valid game item; the check lists unknown items
  3. NPC turn-in — quests turned in at an NPC pay only there
  4. Missing plugin — XP rewards without the XP plugin and achievement or title rewards without KyuubiSoft Achievements pay tokens instead (see Rewards)
  5. 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.


MessageMeaning
”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 lockedYou lack ks.core.admin.dialog.console (see Permissions)
Saving stops and names a fileconfig.json, a language file or an admin file could not be read. Fix the file; Quests does not replace it silently

ToolWhat it does
Admin window → checkFinds broken content before players do
/ksquestadmin debugYour active and completed quests, facts, chapters, streak
/ksquestadmin debugmodeLive 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 meStart, nearly done or reset one quest for yourself
/ksquestadmin reloadReloads 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.