# 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](./admin-panel) 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

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

---

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

---

## 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

**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`.

---

## Texts show as raw keys

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

---

## 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

**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](./rewards#automatic-fallbacks))
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`.

---

## 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](./permissions#the-console-rule)) |
| 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

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