Troubleshooting

Troubleshooting

This page covers the most common issues server owners encounter with the quest system, along with their solutions.

Quests Not Appearing

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

Possible causes:

1. Custom content disabled — Check that config.json has "useCustomContent": true
2. File not in the right folder — Custom quest files must be 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 — Check the server log for parse errors
5. Quest ID collision — If two quests share the same ID, only the last-loaded one survives

Fix: Run /ksquestadmin reload and check the server console for loading messages like:

[INFO] Loaded 42 quest definitions (35 base)
[INFO] Merged 7 custom quests

Objectives Not Tracking

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 internal names exactly. Use debug mode to verify what the server sees
2. Wrong objective type — Make sure the type matches the action (e.g. blocks_mined for mining, entities_killed for combat, items_collected for pickup)
3. Placed block protection — The anti-exploit system ignores blocks the player placed themselves. Blocks become “natural” again after 30 minutes by default (configurable via placedBlockTracker.expiryMinutes)
4. Quest not started — The player must accept the quest first; just having it visible is not enough

Fix: Enable debug mode to see tracking events in real time:

/ksquestadmin debugmode

This logs every tracking event to the server console, showing which items, blocks and entities are being detected and whether they match any active objectives.

NPC Dialog Not Showing

Symptoms: Talking to a quest NPC shows no dialog or the wrong dialog.

Causes: NPC profile citizenId does not match citizens.json, dialog conditions (facts, quest status) not met, or profile JSON missing from quest_npc_profiles/.

Fix: Run /ksquestadmin debug to check the player’s facts and quest status.

Daily/Weekly Quests Not Resetting

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

Possible causes:

1. Reset time not reached — Daily reset defaults to 04:00 in the configured timezone. Check config.json:

   {
     "dailyResetTime": "04:00",
     "weeklyResetDay": "MONDAY",
     "timezone": "Europe/Berlin"
   }

2. Empty quest pool — If the pool has fewer quests than dailyQuestCount (default: 3) or weeklyQuestCount (default: 5), the system cannot rotate properly
3. Pool entries reference non-existent quest IDs — Check the server log for warnings like Daily pool contains unknown quest: some_id

Fix: Verify your pools have enough valid entries. The server log reports pool sizes on startup:

[INFO] Loaded 12 quests in daily pool (10 base)

Localization Not Updating

Symptoms: You added new translation keys but they show as raw key names (e.g. quest.my_quest.name) instead of translated text.

:::danger This is the most common localization issue The localization system uses a file-first pattern with version checking. If the file on disk has the same or higher version than the mod, it is not replaced. :::

Fix:

1. If you are developing the mod: bump _localization_version in both en-US.json and de-DE.json source files and in the CURRENT_LOCALIZATION_VERSION constant in QuestI18n.java
2. If you are a server owner adding custom keys: put them in custom_en-US.json / custom_de-DE.json (no version bump needed for custom files)
3. Run /ksquestadmin reload to pick up file changes

Quest Book Is Empty

Symptoms: Opening the quest book shows no quests at all.

Causes: Config files not extracted yet (restart the server), config loading failed (check logs), or corrupted player data in players/{uuid}.json.

Fix: Run /ksquestadmin reload and verify the console shows lines like Loaded 35 quest definitions (30 base) and Config validation passed.

Rewards Not Granting

Symptoms: Player completes a quest but does not receive rewards.

Possible causes:

1. Inventory full — Item rewards require inventory space. If the inventory is full, the reward may be queued as a pending reward
2. Invalid item ID — The itemId in the reward definition must match a valid game item. Check server logs for warnings
3. Turn-in required — Some quests require turning in at an NPC before rewards are granted. Check if the quest has a turn_in configuration

Fix: Check the quest definition’s reward block:

"rewards": [
  { "type": "item", "itemId": "Ore_Iron", "amount": 5 },
  { "type": "quest_tokens", "amount": 10 }
]

Valid reward types: item, quest_tokens, experience, lootbag, command.

Debug Tools Reference

Command	What it does
/ksquestadmin debug	Shows your active quests, completed quests, facts, chapters, streak
/ksquestadmin debugmode	Toggles live tracking event logging in server console
/ksquestadmin testzone <name>	Simulates entering a zone (for testing zone_entered objectives)
/ksquestadmin testnpc <id>	Simulates interacting with an NPC
/ksquestadmin reload	Reloads all configuration and translation files

Tip

When something is not working, the best first step is always:

1. Run /ksquestadmin debug to check the player’s current state
2. Enable /ksquestadmin debugmode and perform the action to see what the server detects
3. Check the server console log for warnings and errors during config loading

Config Debug Mode

For persistent debug logging, enable debug mode in config.json:

{
  "debug": true
}

This enables additional logging for story quest prerequisites, trigger evaluation, and index building. Useful for diagnosing why story quests are not unlocking or triggers are not firing.